Errors
Every 4xx and 5xx returns one shape. code is always one of the codes below; provider errors keep the provider's own values in provider_code and provider_message.
{ "error": { "code", "message", "request_id", "provider_code"?, "provider_message"?, "param"? } }| Status | Code | Meaning |
|---|---|---|
| 400 | idempotency_key_required | A create request was sent without an Idempotency-Key header. |
| 400 | invalid_amount | amount is not an integer in minor units, or is below the minimum. |
| 400 | invalid_request | A parameter is missing or malformed. param names it. |
| 401 | api_key_invalid | No key, a malformed key, or a key from the other environment. |
| 401 | api_key_revoked | The key was revoked in the dashboard. |
| 403 | initiation_paused | Appears as provider_code on an attempt that was blocked because initiation was paused mid-flight. |
| 403 | business_initiation_disabled | Payments and payouts are paused for this business. Reads, callbacks and webhooks keep working. |
| 404 | not_found | No object with that id for this API key. |
| 409 | idempotency_conflict | The same Idempotency-Key was used within 24 hours with a different body, or the first request is still running. |
| 422 | no_healthy_connection | No healthy provider connection can take this payment method. |
| 422 | capability_unsupported | The connected provider cannot do this operation. Nothing was sent. |
| 422 | insufficient_refundable_balance | The refund is larger than what is left to refund on the payment. |
| 429 | rate_limited | More than 100 requests in a minute for this key. Wait Retry-After seconds. |
| 500 | internal_error | Something failed on our side. Retry with the same Idempotency-Key. |
| 502 | provider_error | The provider returned an error; provider_code and provider_message carry its values verbatim. |