Error reference

Every error from the Commerce API is returned with the same envelope. The HTTP status code tells you the broad category, the error field gives you a stable machine-readable code, and message is a human-readable string suitable for logs but not for cardholders.

{
  "error": "INVALID_REQUEST",
  "message": "The 'amount' field must be a positive integer",
  "requestId": "req_01JQXYZA7B8C9D",
  "details": {
    "field": "amount",
    "value": -100,
    "constraint": "minimum"
  }
}

Severity classes

• transientThe operation might succeed if retried with the same Idempotency-Key. Examples: terminal busy, network blip, rate limit, internal error.
• terminalThe operation will not succeed without operator intervention — re-tap the card, switch entry method, replace the card.
• fatalThe request itself is wrong. Do not retry. Fix the request and try again.

Atlas error codes

Every code in this table maps to a single, stable string in the error field of the response envelope.

ISO 8583 issuer response codes

When the issuer authorizes (or declines) a transaction, the responseCode on the TransactionResponse is the raw ISO 8583 code from the card scheme. "00" means approved; everything else is some flavor of decline. The Retry column tells you what to do programmatically — but always show the cardholder the message printed on their receipt, never the raw code.

Retry policy in one diagram

• Network error before response — retry with same Idempotency-Key. Safe.
• 5xx with transient code — retry with same Idempotency-Key. Safe.
• 408 / 504 — retry with same Idempotency-Key. Safe.
• 429 RATE_LIMITED — honor Retry-After header, then retry.
• 409 TERMINAL_BUSY — wait 1–2s, retry, or call /v1/transaction/{id}/abort first.
• 409 IDEMPOTENCY_CONFLICT — fix the request body. Do not retry.
• 4xx (other) — do not retry. Fix the request.
• 2xx with DECLINED status — the transaction completed cleanly — the issuer just said no. Show the cardholder.

Rate limits

Rate limits are enforced per API key (or per JWT subject) and apply to all endpoints. When you exceed a limit the API returns 429 RATE_LIMITED with a Retry-After header indicating how many seconds to wait before retrying.

Limits are generous enough that a single terminal will never hit them during normal operation. If your integration runs concurrent requests across a fleet of terminals from a single API key, you may need to request a limit increase from your account manager.