When working with APIs, errors can occur due to invalid requests, authorization issues, or system-level conditions. PCE returns standardized error codes and messages to help you identify the root cause and apply the right fix. Proper error handling ensures resilient integrations, reduces downtime, and improves the overall developer experience.

The error responses might contain following information:

Error Code: A unique identifier for the error.
Message: Human-readable description of the error.
Details: Additional context to resolve the issue.
Response Code: A unique code to trace back details of the error message.

The Error messages can be broadly categorized among -

Authentication & Authorization Errors: Example: Invalid API key, expired token, insufficient permissions.
Validation Errors: Example: Missing required fields, invalid parameter values, or incorrect data formats.
Rate Limit Errors: Example: Too many requests in a short timeframe.
Processing & System Errors: Example: Internal server issues or temporary service unavailability.

Authorization Errors

Errors related to login, credentials, and merchant access. A few examples have been listed below.

Error Code	Message	Details
`InvalidCredentials`	Invalid username or password. Please try again.	The login credentials provided are invalid. Check username and password.
`Unauthorized`	Unauthorized	The request is unauthorized. Ensure correct authentication headers and tokens.

Validation Errors

Validation errors occur when a payment request or customer/card data does not meet the required format or rules. When a validation error occurs, the API response includes:

"errorCode": "ValidationError"
"message": "Validation error happened"
A "details" field that describes the specific issue.

Below are some common examples of validation errors for:

a. Payment entity

Details	Description
"merchantId required"	When using our make a payment API. Please include the merchantId in your code. This is a required field.
"Could not convert string to integer: '. Path 'merchantId', line 2, position 21.", "merchantId required"	This error is caused by sending in special characters instead of an int or string in the merchantId field.
"Unexpected character encountered while parsing value: ,. Path 'merchantId', line 2, position 19." "After parsing a value an unexpected character was encountered: ". Path 'merchantId', line 3, position 4."	This error is caused by sending in a the merchantId variable with no value or null assigned to it.
"Could not convert string to integer: 5161589748. Path 'merchantId', line 2, position 30.", "merchantId required"	This is caused by sending in a `mechantId` that is longer then 9 digit.
"Must specify valid information for parsing in the string.", "tenderType required. Must be one: Card, Check, Cash, or ACH."	When using the TenderType field, the value needs to be Card, Check, Cash, or ACH.
"Cannot insert the value NULL into column 'PaymentTypeId', table 'MXG.dbo.Transaction_Batch'; column does not allow nulls. INSERT fails.::batch::::MID=516158974::PTId=NULL\r\nAn invalid application lock resource was passed to xp_userlock.::NULL::OId=NULL"	This error is caused by sending in a number instead of string in the `tenderType` field.
"Input string was not in a correct format."	This error occurs when you send in a string instead of an int for the amount field.
"Missing Account Information"	This error is caused by leaving the number field empty.
"Invalid card number, no spaces allowed StringErrorTest"	This error is caused by sending in a string instead of an integer in the number field
"Year, Month, and Day parameters describe an un-representable DateTime."	This error is caused by sending in an invalid Int for the epiryMonth/epiryYear field.
"Input string was not in a correct format."	This error is caused by sending a string instead of an integer in the `expiryMonth` field
"Missing expiration month and / or year"	This error occurs when you send in the expiryMonth field with no value.
"Value was either too large or too small for an Int32."	This error occurs when the integer you send in with expiryYear/expiryMonth is too large to be int32.
"Incorrect zipcode format"	This error occurs when you send in any value besides numbers. This can also happen from submitting none 5 digit numbers.

b. Customer entity

Details	Description
"merchantId required"	When using our make a payment API. Please include the merchantId in your code. This is a required field.
"Could not convert string to integer: '. Path 'merchantId', line 2, position 21.", "merchantId required"	This error is caused by sending in special characters instead of an int or string in the `merchantId` field.
Unexpected character encountered while parsing value: ,. Path 'merchantId', line 2, position 19.","After parsing a value an unexpected character was encountered: ". Path 'merchantId', line 3, position 4."	This error is caused by sending in a the merchantId variable with no value or null assigned to it.
"Could not convert string to integer: 5161589748. Path 'merchantId', line 2, position 30.","merchantId required"	This is caused by sending in a `mechantId` that is longer than 9 digit.
"address1 has to be at least 5 characters long"	This error occurs when you send a value that has less then 5 characters.
"state is required"	This error occurs when you don't send in the state field and the state field is empty.
"Incorrect zipcode format"	This error occurs when you send in any value besides numbers. This can also happen from submitting none 5 digit numbers.
"Must specify valid information for parsing in the string."	This error is caused by sending in the customerType field empty.
"Requested value '@@' was not found."	This error is caused by sending special characters in the customerType field

System & Generic Errors

These include the unexpected or system-level errors. A few examples have been listed below.

Error Code	Error Message	Description
ContactCustomerSupport	An error has occurred. Please contact customer support.	An unexpected error occurred. Contact customer support for assistance.

Best Practices

Always check the HTTP status first to determine if the error is at the protocol or data level.
Parse error codes and messages to decide corrective actions (e.g. retry, prompt user input).
Log errors with full context (endpoint, request payload, error code) for debugging.
Implement retry logic for transient server errors (5xx) with exponential backoff.