Errors and rate limits

The error envelope, what each code range means, and how to handle rate limits.

The error envelope

API request errors return a consistent object. An error can occur before or after submission to the payment gateway:

{
  "code": 2000,
  "status": "Rejected",
  "message": "One or more validation errors occurred.",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": [
    {
      "code": 2000,
      "field": "Amount",
      "message": "Request validation failed",
      "details": "The Amount field must be a positive number between 1 and 999,999,999."
    }
  ]
}

Always log traceId. It is the single fastest way for support to find your request.

status is what tells you whether to retry

status is the execution status of the request against the payment gateway, and it is the field that decides your retry behaviour.

Duplicate-reference errors

The API uses referenceId to prevent duplicate transaction requests. The duplicate-reference validation check returns HTTP 400, code 2000, and status Rejected when the reference is already in use for that merchant. The error indicates that a request already exists; it does not tell you whether that earlier request succeeded, failed, or is still processing. The API does not replay its response.

Retrieve the existing transaction by the request's own referenceId and inspect its outcome. Do not change the reference just to get past this error: a new reference identifies a separate operation and can cause the operation to execute again. See Preventing duplicate requests.

Error code ranges

code is a numeric error code, grouped into ranges so you can branch on the range rather than on every individual value.

The complete enumeration, with a description for every individual code, is on the Error schema in the API reference.

Transaction result codes are different

Transaction responses use resultCode and, when available, resultText. These are distinct from code and message in an error envelope:

• 0 - the transaction request was successful. Check each transactionResponse's responseCode to determine whether the transaction was approved or declined.
• 1010 - the transaction request is pending customer interaction.
• 2014 - the payment method or card brand is not enabled for the merchant. resultText is the message, such as Visa cards are not enabled for this merchant., in sentence case; every other resultText on a stored transaction is uppercase. A token sale or authorization also returns it as an HTTP 400 error with code 2014.
• 4100 - a token payment requires a cardholder challenge. Follow threeDsChallenge.redirectUrl and reconcile the outcome before retrying.
• 4001 - the transaction is being processed. Returned for asynchronous bank transfer payment methods such as ACH while awaiting a final outcome.
• 1003, 1005, 3002, 3005, 3006, 3009 - terminal-specific conditions on card present transactions, such as a busy, low-battery, or disconnected terminal.
• 6800-6802 - 3D Secure outcomes on declined card-not-present transactions.
• 6900-6902 - hosted payment form and Payment SDK card outcomes: an issuer decline, a gateway failure, or a missing payment token. See SDK error codes.

The full resultCode enumeration is on the ResultCode schema in the API reference.

Transaction response codes

responseCode is the field that tells you whether a transaction succeeded. Each entry in transactionResponses carries one. The HTTP status, resultCode, and status do not tell you whether the payment was approved.

A transaction succeeded only when status is Completed and transactionResponses contains an entry with responseCode 1 (approved) or 2 (partially approved). Every other code means the payment was not approved:

• Declined - the issuer or bank refused the payment. Do not retry with the same payment details; ask the customer for another payment method.
• Canceled - the customer or merchant stopped the transaction. No money moved.
• Pending - the outcome is not final. Do not treat it as a success or a failure; wait for the webhook or query the transaction again.
• Unknown (0) - no specific code was reported. While status is not Completed, treat it like Pending. On a Completed transaction it is a failure, not an approval: read resultCode and resultText for the reason, for example 2014 or 6901.
• Error - processing failed for a technical or request reason. Fix the cause before you retry.

transactionResponses is empty while processing is incomplete, so an empty array is not a decline.

On a Chargeback transaction, responseCode 1 means the chargeback took effect: the money went back to the payer. It is not a payment to you. For a partial approval, only amountApproved was approved; collect the balance another way.

Branch on the number; the name is for reference only.

The same list is on the ResponseCode schema in the API reference.

HTTP status codes

Rate limiting

If you receive 429 Too Many Requests, pause before retrying. Honor Retry-After when supplied; otherwise use exponential backoff. The public API does not guarantee X-RateLimit-Limit, X-RateLimit-Remaining, or X-RateLimit-Reset headers.