Handle errors

Know when to fix, retry, recover, or ask for another card.

API errors use the HTTP status and a JSON error message. Do not build logic around the exact message text; use the status code and the payment fields documented by the endpoint.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ "error": "Idempotency-Key is required and must be at most 120 characters" }

Declines are results, not API failures

A request can be processed successfully while the issuer declines the card. Money-path endpoints return a normal response containing approved: false, a payment status, and usually an issuer response code. Do not retry the same card automatically.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "approved": false,
  "responseCode": "51",
  "message": "Your card was declined. Please try another card.",
  "payment": { "status": "DECLINED" }
}

What to do for each status

400Fix the requestA field is missing or invalid. Do not retry unchanged.

401 / 403Fix authenticationUse the right credential and verify it belongs to this account or terminal.

404Check the IDThe resource does not exist or is not visible to this account.

409 / 422Read the errorThe request conflicts with current state or cannot be processed. Do not blindly retry.

429WaitRespect Retry-After when present, then retry with the same idempotency key.

500 / 502 / 503 / 504Retry safelyRetry with the same idempotency key. For terminal authorizations, use recovery if the outcome is uncertain.

Never guess after a timeout

A timeout does not mean the payment failed. The issuer may have approved it before the response was lost. Reuse the original idempotency key; terminal integrations can also call the recovery-status endpoint to learn whether to finish the card interaction, reverse the authorization, or close the attempt locally.

See Safe retries and Handling declines.