Errors
Use stable error codes to decide whether to retry or fix a request.
On this page
Error response
Errors have an HTTP status and {error: {code, message}}. The message explains the issue to a person and can change. Branch on the code.
JSON
{
"error": {
"code": "idempotency_conflict",
"message": "The idempotency key was used for a different request"
}
}Common status codes
| Field | Details |
|---|---|
400 malformed_requestfix request | Malformed JSON or a missing/invalid required header. Some invalid list parameters also return 400. |
401 unauthorized / invalid_api_keyfix authentication | Missing Bearer credentials, or an invalid, revoked or expired key. |
403 forbiddenfix access | Wrong profile or missing scope. |
404 invoice_not_found / payment_not_found / store_not_foundcheck identity | The object does not exist within the caller’s permitted profile, store and mode. |
409 idempotency_conflictresolve conflict | A reused key has different purchase terms. Do not blindly issue a new key. |
409 billing_details_requiredcomplete setup | Save profile billing details in the app before creating a payment. |
422 invalid_valuefix value | A field, token choice or store violates the operation’s rules. |
429 rate_limitedretry later | Wait the seconds provided in Retry-After. |
500 internalretry carefully | Unexpected server error. Retry creates with the original idempotency key. |
503 network_not_readyretry later | Network setup or readiness is incomplete. |
Retry without duplicating an order
Keep your original idempotency key after a timeout or retryable failure. Read an existing order’s stored session before deciding to create another attempt.
Do not retry validation failures unchanged. Do not expose server secrets in logs or error messages.