Errors
Every error has the same body:
JSON
{ "error": { "code": "invalid_request", "message": "Human-readable explanation", "issues": [] } }Branch on code (stable), never on message. Extra fields (issues, refundable, retryAfterSeconds,
explanation, reasons) depend on the error.
| HTTP | Typical codes | What to do |
|---|---|---|
| 400 | idempotency_key_required |
Add a valid Idempotency-Key. |
| 401 | unauthorized |
Check the key; it may be revoked. |
| 403 | forbidden, merchant_blocked |
The role cannot do this, or the account is paused. |
| 404 | not_found |
The object does not exist for your merchant (objects of other merchants are never visible). |
| 409 | request_in_progress, store_routing_paused, price_changed, … |
A state conflict; read the object and decide. |
| 422 | invalid_request (with issues), idempotency_key_reused, payment_blocked (risk rules), no_eligible_route, refund_*, publish_validation_failed, … |
Fix the request; the operation was not done. |
| 429 | rate_limited |
Wait Retry-After seconds. |
| 502 / 503 | provider_unavailable, reconcile_pending, capture_unconfirmed |
A processor or the switch did not answer. Retry with the same idempotency key, or sync; never assume failure. |
A POST /v1/payments that no processor can take returns 200 with status: "failed" (the payment exists and records
why).