Error Codes

Error Response Payload

Cards Connect will return one of these HTTP status codes in the error response:

These are the standard error fields included as part of the response:

Field	Type	Description
type	URL	Link to the HTTP status code definition
title	String	Describes the type of error - indicates if business rule related
status	Number	HTTP status code
errors	Object	Contains the error details
errors.key - key name	String	The name of the field containing the error.
errors.key	Array of String	Each element in the array contains the details of the validation error

400 Bad Request

This is used to indicate that request payload format is invalid.

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "reconciliationId": [
      "The ReconciliationId field is required."
    ]
  },
  "traceId": "00-66dcc869c9943e961a69464cf0a8f9ac-8ae5bc23410ea958-00"
}

422 Unprocessable Content

This is used to indicate that the format of the request payload is correct, but the content of the message violates one or more business rules.

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.21",
  "title": "One or more business validation errors occurred.",
  "status": 422,
  "errors": {
    "amount": [
      "Amount must not exceed merchant limit"
    ]
}

Generic Transaction Errors

Error Code	Error Description	HTTP Status Code	Detail
TRAN01	Merchant is not transaction ready	422	Merchant is not yet activated or a key parameter is missing in the merchant profile.
TRAN02	Transaction already exists	422	This is an idempotency error that is thrown whenever an authorization already exists during an auth call for that merchant
TRAN03	Invalid card expiry	422	The format of the card expiry does not match MM/yy Or, the card is expired.

Authorisation Errors

Error Code	Error Description	HTTP Status Code	Detail
AUTH01	The supplied Authorization header value is not a JWT token	401	Self-explanatory
AUTH02	The authentication token is missing the keyId field	401	Self-explanatory
AUTH03	The supplied keyId does not match a known credential	401	Self-explanatory
AUTH04	The credential has expired	401	Self-explanatory
AUTH05	The authentication token did not pass JWT validation. Possible causes include: expired token, invalid signature or other JWT validation error. The error summary is included in the error message	401	Self-explanatory
AUTH06	The method claim in token does not match the HTTP method requested	401	Self-explanatory
AUTH07	The path claim in the token does not match the HTTP path requested	401	Self-explanatory
AUTH08	The query claim in the token does not match the HTTP query parameters requested	401	Self-explanatory
AUTH09	A request body was supplied but the sha256 claim on the token is not present	401	Self-explanatory
AUTH10	A sha256 claim is present on the token but no request body was supplied	401	Self-explanatory
AUTH11	The computed sha256 hash of the request body does not match the sha256 claim in the token	401	Self-explanatory
AUTH12	The application experienced an unexpected error while executing the JWS Authorization Handler	401	Self-explanatory
AUTH20	The credential is not authorized to access the Merchant Id header value	401	Self-explanatory
AUTH21	The application experienced an unexpected error while executing the JWS Authorization Handler (internal to AuthenticationCredentialProvider)	401	Self-explanatory