Reference

Errors

All our HTTP codes and error.code values in one place, plus a failure_code reference for bank declines.

Every error is JSON in a single shape, with a suitable HTTP status:

{
  "error": {
    "code":    "method_not_supported_by_bank",
    "message": "bank does not support the chosen method"
  }
}

What you may encounter:

HTTP	code	when
`400`	`bad_request`	invalid body or a required field is missing
`401`	`unauthorized / invalid_token`	no key, expired or invalid key
`401`	`signature_required`	shop requires signing, X-PSP-Signature header not provided
`401`	`invalid_signature`	X-PSP-Signature does not match what we computed over the body
`403`	`live_not_enabled`	sk_live but the merchant has not been activated yet
`403`	`ip_not_allowed`	IP outside the shop allow-list
`403`	`aml_blocked`	payment rejected by our AML scoring
`403`	`forbidden_purpose`	description or order_id contains forbidden content; account is held for review
`404`	`not_found`	object not found or belongs to a different merchant
`409`	`not_pending`	payment is no longer in pending (cancel only)
`409`	`not_refundable`	refund is only possible on a succeeded payment
`409`	`fully_refunded`	payment is already fully refunded
`422`	`amount_too_large`	refund amount exceeds the remaining balance
`422`	`route_not_configured`	no connector configured for the (shop, method) pair
`422`	`method_not_supported_by_bank`	acquiring bank does not support the chosen method
`429`	`rate_limited`	merchant public-API limit exceeded; see Retry-After
`500`	`db_error / internal`	internal error
`502`	`router_error`	bank call failed

Failure codes

The POST /payments response and the payment.failed webhook contain a failure_code field. This is our unified code, not the raw bank response. Only we talk to the bank; the raw bank code is kept internally for audit and is not exposed.

failure_code	when
`insufficient_funds`	`not enough funds on the payer’s account`
`card_declined`	`card declined by the bank (generic case, no specifics)`
`card_expired`	`card expired`
`do_not_honor`	`bank refused to honor the operation (CVV fail, 3DS fail, etc.)`
`fraud_blocked`	`blocked by anti-fraud (ours or the bank’s)`
`limit_exceeded`	`card, merchant or sandbox limit exceeded`
`aml_blocked`	`rejected by our AML scoring`
`customer_cancelled`	`customer cancelled on the bank page`
`timeout`	`bank did not return a final status before the session TTL`
`bank_unavailable`	`bank is down or returned 5xx; retry later`
`bank_unknown`	`bank returned a non-standard code; check failure_message`

failure_message is a human-readable description for UIs. Safe to show directly on an error page to the customer.