Error codes
A single call carries three layers of codes, each answering a different question. Most integration problems come from collapsing them into one.
Tell the three layers apart
| Layer | Answers | Found in |
|---|---|---|
| HTTP | Did we accept the call? | 200 / 4xx / 5xx |
| Business | Was the request itself valid? | biz_code + code |
| Payment outcome | Did the money actually move? | attempt.unified_code |
HTTP 200 does not mean the payment succeeded. On a provider decline the status is 200 and there is no code field at all — the failure lives in status and attempts[].unified_code. Judging a payment by its HTTP status is the most common and most expensive way to get this wrong.
Business code ranges
biz_code is a four-digit number mapped one-to-one onto the string code. Switch on the number, log the string — you get both so you never have to maintain a mapping table.
{
"code": "refund_exceeds_captured",
"biz_code": "4012",
"message": "refund amount exceeds captured amount",
"details": [{ "field": "amount", "reason": "max_refundable_is_6900" }],
"request_id": "req_3f9a2c"
} | Range | Category | How to handle |
|---|---|---|
0 | Success | Not an error. HTTP 2xx with no code field |
1xxx | Authentication and signing | Keys, signatures, timestamps, nonces, environments. Fix the configuration, do not retry |
2xxx | Request validation | The request body itself is invalid; details points at the field. Fix it and resend |
3xxx | Idempotency and concurrency | Idempotency-Key missing or conflicting |
4xxx | State does not allow it | The object cannot do this in its current state. Check status and available_actions first |
5xxx | Providers and routing | Provider decline, timeout, unsupported operation, or nothing available |
6xxx | Quota and rate limiting | Merchant quota exceeded. Stop immediately and back off per Retry-After |
9xxx | Internal | Our problem. Report it with the request_id; retrying with the same key and backoff is safe |
All business error codes
These are returned with a code field, which means the request never reached the payment flow.
| biz_code | code | HTTP | Retry? | Cause | How to check |
|---|---|---|---|---|---|
| 4002 | refund_not_found | 404 | No | The refund does not exist, or belongs to another environment | Refund references start with RF — do not confuse them with the PY payment reference |
| 4021 | payout_not_cancellable | 409 | No | The payout has already gone to the provider and cannot be recalled | Only created (awaiting approval) can be cancelled. Once processing, you must wait for the outcome; a failure returns the funds to your balance automatically |
| 4040 | file_too_large | 413 | No | A single file is over 10 MB | Compress the evidence first. Split material across several uploads — the evidence endpoint accepts multiple file_ids |
| 4041 | file_type_unsupported | 400 | No | The file type is not on the allowlist | Only pdf / jpg / png / tiff. The card networks reject anything else, so we block it up front rather than letting you lose the dispute |
| 4050 | routing_version_conflict | 409 | No | The version you published is not the current one, so someone changed the rules before you | GET the latest rule set, merge your change and resubmit. This is optimistic locking, not a fault |
| 4051 | routing_invalid_rule | 400 | No | A rule references a provider that does not exist or was disabled, or a condition field is misspelled | Dry-run it first with POST /v1/routing/simulate. Do not publish straight to live |
| 4060 | export_not_ready | 409 | Yes | The export job is still running | Poll GET /v1/finance/exports/{uid} until status=ready, or subscribe to the webhook. Large exports usually take tens of seconds |
| 4070 | webhook_url_insecure | 400 | No | The webhook URL is not https, or points at a private or reserved address | It must be a publicly reachable https URL. We never deliver signed events over http |
| 1001 | auth_key_missing | 401 | No | The request carried no Authorization header, or it was not a Bearer token | Check the header reads Authorization: Bearer sk_live_xxx, with a single space after Bearer |
| 1002 | auth_key_invalid | 401 | No | The key does not exist, was revoked, or was auto-revoked by GitHub secret scanning | Check the key's state under Developers → API keys. An auto-revocation means it leaked into a public repository and must be replaced |
| 1003 | auth_env_mismatch | 401 | No | An sk_test_ key was used against the live host, or the reverse | The key prefix must match the host's environment. This guard exists to stop test code reaching production — do not work around it |
| 1010 | auth_signature_invalid | 401 | No | The signature is wrong. Nine times out of ten the body was re-serialised | Hash the exact bytes you send with SHA-256; do not deserialise and re-stringify. Check the order of the six segments and that the separator is a newline |
| 1011 | auth_timestamp_expired | 401 | Yes | X-Timestamp is more than ±300 seconds from server time | Fix NTP on your server rather than widening the window |
| 1012 | auth_nonce_replayed | 401 | No | The same X-Nonce was used twice within 10 minutes | Generate a fresh nonce per request. On a retry, change the nonce and timestamp but keep the Idempotency-Key |
| 1020 | auth_browser_origin_rejected | 401 | No | The request carried a browser Origin / Referer header, meaning the secret key is in your frontend | Revoke that key immediately. The public API is server-side only; the browser uses a publishable key and a client token |
| 2001 | validation_failed | 400 | No | Invalid parameters; details points at the specific field | Fix according to details[].field and reason. Amounts are positive integers in the minor unit, not decimals |
| 2010 | validation_currency_unsupported | 400 | No | The currency is not enabled, or no route is available for it | Check under Connectors → capability matrix whether an enabled route exists for that currency |
| 2020 | validation_encrypted_field_required | 400 | No | A card number, CVV or payout account was submitted in plaintext | These fields must use a digital envelope (the encrypted object) or JWE; plaintext is always rejected |
| 3001 | idempotency_key_missing | 400 | No | The POST carried no Idempotency-Key | Every POST needs one; UUID or ULID is recommended |
| 3002 | idempotency_key_conflict | 409 | No | The same Idempotency-Key was reused with a different body | This is protecting you — change the amount, change the key. Reusing the old key means your keys are not derived from your order reference |
| 4001 | payment_not_found | 404 | No | The payment does not exist, or belongs to another environment or merchant | Check the uid for typos and that the key's environment matches the one it was created in |
| 4010 | payment_not_capturable | 409 | No | The status is not authorized, or capture_mode is not manual | Read available_actions first; it is computed server-side and is more reliable than inferring from status |
| 4011 | payment_not_refundable | 409 | No | Not captured, or past the provider's refund window | Use void to release an uncaptured authorization — not refund |
| 4012 | refund_exceeds_captured | 409 | No | Cumulative refunds would exceed the captured amount | Enforced by a single conditional UPDATE server-side, so concurrent duplicates cannot over-refund. Compute the refundable amount as captured_amount - refunded_amount |
| 4013 | payment_already_terminal | 409 | No | The payment is already in the terminal failed / cancelled state | Terminal states are irreversible. A late success webhook will not flip it; a genuine reversal goes through manual remediation |
| 5001 | connector_declined | 200 | Depends | Provider decline. Read unified_code and decline_type on the attempt | For soft we have already cascaded, so do not retry; never retry hard — it only worsens the risk profile |
| 5002 | connector_timeout | 200 | No | Provider timeout, outcome unknown | This is not a failure. Do not retry it as one (you risk a double charge); query the payment to converge, or wait for reconciliation |
| 5010 | connector_unsupported_operation | 409 | No | The provider does not support this operation (adjusting an authorization, for example) | Check under Connectors → capability matrix which operations that provider supports |
| 5011 | connector_unavailable | 503 | Yes | Every candidate provider is unavailable, or the circuit breaker is open | Check Connector health in the console. Back off and retry with the same Idempotency-Key |
| 4020 | payout_approval_required | 202 | No | The amount is over your threshold and went to dual approval | Not an error. Once approved, a payout.status_changed webhook follows |
| 4030 | dispute_evidence_window_closed | 409 | No | Past evidence_due_at | The evidence window is set by the card networks and cannot be extended. Subscribe to dispute.opened and set a reminder |
| 6001 | rate_limited | 429 | Yes | Merchant quota exceeded | Stop immediately and wait for Retry-After. Continuing will get you temporarily blocked |
| 9001 | internal_error | 500 | Yes | A problem on our side | Report it with the request_id. Retrying with the same Idempotency-Key and backoff is safe |
"Retry: yes" assumes the same Idempotency-Key. Retrying with a new key opens a second payment — in this business, that is a double charge.
Unified decline codes (HTTP 200, payment failed)
A provider decline is not an API error, so the status is 200 and there is no code field. Every provider uses its own raw codes; we map them onto a single unified_code that is comparable across providers, countable, and usable in routing rules.
HTTP/1.1 200 OK <- the call succeeded
{
"uid": "PY20261116000217A7F3",
"status": "failed", <- the payment did not
"is_terminal": true,
"attempt_count": 2,
"attempts": [
{ "attempt_no": 1, "connector_code": "stripe",
"status": "failed", "provider_code": "05",
"unified_code": "do_not_honor", "decline_type": "soft" },
{ "attempt_no": 2, "connector_code": "adyen", "is_fallback": true,
"status": "failed", "provider_code": "51",
"unified_code": "insufficient_funds", "decline_type": "soft" }
]
} Two kinds of decline, handled in opposite ways
| soft | Might succeed on another provider. We have already cascaded to a backup route, so do not retry yourself — all you would add is double-charge risk. |
| hard | Will not succeed anywhere. We stop cascading immediately. Retrying only raises your fraud ratio and can get the card locked by the issuer. |
soft declines (8)
| biz_code | unified_code | Meaning | Typical raw code | What to do |
|---|---|---|---|---|
| 5101 | insufficient_funds | Insufficient funds or credit | Stripe card_declined · Visa 51 | Cascading to a backup provider will not help (same card). Ask the buyer to use another card or try later |
| 5102 | do_not_honor | The issuer declined without stating a reason — by far the most common decline | Visa 05 · Adyen Refused | The decline most worth cascading: it often succeeds through a different acquirer. We cascade automatically by default |
| 5103 | issuer_unavailable | The issuer's systems are unavailable | Visa 91 | Cascades automatically. If every provider returns this, the fault is on the issuer's side |
| 5104 | processing_error | Processing error at the provider or issuer | Visa 96 | Cascades automatically |
| 5105 | exceeds_limit | Per-transaction or cumulative limit exceeded | Visa 61 / 65 | Ask the buyer to split the payment or use another card. Cascading will not help |
| 5106 | velocity_limit | Too many attempts in a short window | Visa 65 | Stop retrying. Continuing will trip the issuer's risk controls and lock the card |
| 5107 | try_again_later | The issuer asked you to try again later | Adyen Acquirer Error | Cascades automatically; if every route fails, ask the buyer to retry later |
| 5108 | three_ds_required | The issuer requires 3DS authentication | Visa 1A | Not a failure. Redirect per attempt.action, then call resume once complete |
hard declines (11, never retry)
| biz_code | unified_code | Meaning | Typical raw code | What to do |
|---|---|---|---|---|
| 5201 | authentication_failed | 3DS authentication failed or was abandoned by the buyer | Adyen AuthenticationFailure | Do not retry. Have the buyer start a new payment |
| 5202 | lost_or_stolen_card | The card has been reported lost or stolen | Visa 41 / 43 | Never retry. Retries are recorded as suspicious behaviour |
| 5203 | pickup_card | The issuer asked for the card to be retained | Visa 04 / 07 | Never retry |
| 5204 | expired_card | The card has expired | Visa 54 | Ask the buyer to update the expiry date. A stored card returning this should trigger your card-update flow |
| 5205 | invalid_card_number | The card number does not exist or fails validation | Visa 14 | Check how you collect card numbers. A vault token returning this means the card has been closed |
| 5206 | account_closed | The account has been closed | Visa 78 / 79 | Do not retry. Delete the stored card token |
| 5207 | restricted_card | The card is restricted from this type of transaction | Visa 62 | Common on cross-border and digital-goods payments. A different currency or a local provider may work |
| 5208 | transaction_not_permitted | The issuer does not permit this type of transaction | Visa 57 | As above. Check that your MCC matches the provider |
| 5209 | fraud_suspected | The provider or issuer judged this fraudulent | Visa 59 · Adyen FRAUD | Never retry, and review the order. Retrying raises your fraud ratio |
| 5210 | blocked_by_rule | Matched one of your own risk rules or BIN blocklists | — | Not a provider decline. Check which rule fired under Risk in the console |
| 5211 | currency_not_supported | The provider does not support this currency | — | A routing configuration problem, not a buyer problem. Check the provider capability matrix |
Neither soft nor hard
| biz_code | unified_code | Meaning | Typical raw code | What to do |
|---|---|---|---|---|
| 5002 | connector_timeout | Provider timeout, outcome unknown | — | Neither a failure nor a success. Do not retry; query the payment to converge, or wait for reconciliation |
Never show unified_code or message to the buyer as-is. Telling a buyer fraud_suspected tells a fraudster which rule fired; insufficient_funds on a shared account is a privacy leak. To the buyer, say only that the payment did not go through and offer another method.