Error Codes
View the list of errors you may encounter
Card Present Gateway
If you want to access information about our in-store offering, you may check the API specifications here: In-store Transactions Overview
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. |
| TRAN04 | Transaction cannot be found | 404 | The merchant has tried to take an action (E.g. Capture) on a transaction that does not exist for that merchant. |
| TRAN05 | The transaction is currently being processed | 422 | The merchant requested an event for a transaction that is being processed by another request that may change the state of the transaction |
| TRAN06 | The currency in the request is not accepted by the merchant | 422 | The currency passed in the authorisation API is not the settlement currency of the merchant’s acquirer, hence, not accepted by the merchant. |
| TRAN07 | The system is working on a previous request that may change the state of the transaction | 422 | The system is retrying to recover from an ambiguous state (E.g. An initially accepted Capture had failed to be delivered to the schemes) |
| TRAN08 | The merchant doesn't have any active terminals to transact with | 422 | A transaction request is made for a merchant that doesn't have any active terminals. |
| TRAN09 | Merchant status needs to be active for this operation | 422 | A transaction or any other type of operation request is made for an inactive merchant. |
| TRAN11 | Request cannot be processed due to a failed recovery of a previous operation leaving the transaction at an ambiguous state. | 422 | The retry attempts to recover from a failed state such as a failed Refund, Void, or Capture also failed, leaving the transaction in an ambiguous state permanently. |
| CAPTURE01 | Transaction is already captured | 422 | A transaction has an accepted Capture record on it and the merchant has requested another Capture |
| CAPTURE02 | Transaction cannot be captured as the authorization has either been declined or failed | 422 | The merchant requested a Capture for a declined or failed authorization |
| CAPTURE03 | Transaction cannot be captured as it has been refunded | 422 | The transaction has at least one successful refund record on it and the merchant has requested a Capture |
| CAPTURE04 | Transaction cannot be captured as it has been voided | 422 | The merchant requested a Capture for a voided authorization |
| CAPTURE05 | Merchant is not configured to Over-capture. | 422 | Over-capture parameter in the merchant config is set to “No” for a merchant that is trying to Over-capture. |
| CAPTURE06 | Total capture amount exceeds merchant’s over capture limit | 422 | Over-capture amount exceeds either the percentage or the amount-based limit specified in the merchant config. |
| CAPTURE07 | Capture cannot be found | 404 | The Capture id provided to the GET Capture API cannot be found under the respective transaction. |
| CAPTURE08 | Transaction already exists | 409 | This is an idempotency error that is thrown whenever a capture already exists during a capture call for that merchant |
| VOID01 | Transaction is already voided | 422 | The merchant requested a void for a transaction that was already voided |
| VOID02 | Transaction cannot be voided as the authorization has either been declined or failed | 422 | The merchant requested to void a declined or failed authorization |
| VOID03 | Transaction cannot be voided as it has been captured | 422 | The merchant requested to void a captured authorization |
| VOID04 | Transaction cannot be voided as it has been refunded | 422 | The merchant requested to void a refunded authorization |
| VOID05 | Void cannot be found | 422 | The Void id provided to the GET Void API cannot be found under the respective transaction. |
| VOID06 | There isn’t any outstanding authorization amount to void | 422 | There’s no additional authorisation amount that is not already captured or voided on the transaction |
| VOID07 | Transaction already exists | 409 | This is an idempotency error that is thrown whenever a void already exists during an void call for that merchant’s authorization |
| REFUND01 | Transaction cannot be refunded as the authorization has either been declined or failed | 422 | The merchant requested to refund a declined or failed authorization |
| REFUND02 | Transaction cannot be refunded as it has been voided | 422 | The merchant requested to refund for a voided authorization |
| REFUND03 | Transaction cannot be refunded as it hasn’t been captured | 422 | The merchant requested to refund for a transaction that doesn’t have a capture on it |
| REFUND04 | Refund cannot be found | 422 | The Refund id provided to the GET Refund API cannot be found under the respective transaction. |
| REFUND06 | Total refund amount cannot exceed total capture amount | 422 | The total refund amount exceeds the total capture amount on a transaction |
| REFUND09 | Transaction already exists | 409 | This is an idempotency error that is thrown whenever a refund already exists during an refund call for that merchant’s authorization |
| ASI01 | The operation is not allowed for an Account Status Inquiry transaction | 422 | A subsequent operation (E.g. A capture) is requested for an account status inquiry (ASI) transaction |
Authorisation Errors
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 |
Updated 15 days ago