● Error codes · 33 business + 20 decline

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

LayerAnswersFound in
HTTPDid we accept the call?200 / 4xx / 5xx
BusinessWas the request itself valid?biz_code + code
Payment outcomeDid 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"
}
RangeCategoryHow to handle
0SuccessNot an error. HTTP 2xx with no code field
1xxxAuthentication and signingKeys, signatures, timestamps, nonces, environments. Fix the configuration, do not retry
2xxxRequest validationThe request body itself is invalid; details points at the field. Fix it and resend
3xxxIdempotency and concurrencyIdempotency-Key missing or conflicting
4xxxState does not allow itThe object cannot do this in its current state. Check status and available_actions first
5xxxProviders and routingProvider decline, timeout, unsupported operation, or nothing available
6xxxQuota and rate limitingMerchant quota exceeded. Stop immediately and back off per Retry-After
9xxxInternalOur 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_codecodeHTTPRetry?CauseHow 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

softMight 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.
hardWill 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_codeunified_codeMeaningTypical raw codeWhat to do
5101insufficient_funds Insufficient funds or creditStripe card_declined · Visa 51 Cascading to a backup provider will not help (same card). Ask the buyer to use another card or try later
5102do_not_honor The issuer declined without stating a reason — by far the most common declineVisa 05 · Adyen Refused The decline most worth cascading: it often succeeds through a different acquirer. We cascade automatically by default
5103issuer_unavailable The issuer's systems are unavailableVisa 91 Cascades automatically. If every provider returns this, the fault is on the issuer's side
5104processing_error Processing error at the provider or issuerVisa 96 Cascades automatically
5105exceeds_limit Per-transaction or cumulative limit exceededVisa 61 / 65 Ask the buyer to split the payment or use another card. Cascading will not help
5106velocity_limit Too many attempts in a short windowVisa 65 Stop retrying. Continuing will trip the issuer's risk controls and lock the card
5107try_again_later The issuer asked you to try again laterAdyen Acquirer Error Cascades automatically; if every route fails, ask the buyer to retry later
5108three_ds_required The issuer requires 3DS authenticationVisa 1A Not a failure. Redirect per attempt.action, then call resume once complete

hard declines (11, never retry)

biz_codeunified_codeMeaningTypical raw codeWhat to do
5201authentication_failed 3DS authentication failed or was abandoned by the buyerAdyen AuthenticationFailure Do not retry. Have the buyer start a new payment
5202lost_or_stolen_card The card has been reported lost or stolenVisa 41 / 43 Never retry. Retries are recorded as suspicious behaviour
5203pickup_card The issuer asked for the card to be retainedVisa 04 / 07 Never retry
5204expired_card The card has expiredVisa 54 Ask the buyer to update the expiry date. A stored card returning this should trigger your card-update flow
5205invalid_card_number The card number does not exist or fails validationVisa 14 Check how you collect card numbers. A vault token returning this means the card has been closed
5206account_closed The account has been closedVisa 78 / 79 Do not retry. Delete the stored card token
5207restricted_card The card is restricted from this type of transactionVisa 62 Common on cross-border and digital-goods payments. A different currency or a local provider may work
5208transaction_not_permitted The issuer does not permit this type of transactionVisa 57 As above. Check that your MCC matches the provider
5209fraud_suspected The provider or issuer judged this fraudulentVisa 59 · Adyen FRAUD Never retry, and review the order. Retrying raises your fraud ratio
5210blocked_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
5211currency_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_codeunified_codeMeaningTypical raw codeWhat to do
5002connector_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.