Reference
Errors
Error format, HTTP statuses and failure codes.
The error body
{
"error": "quote_expired",
"message": "That price expired. Get a new price to continue.",
"requestId": "req_demo_0f3a"
}error is a stable code to program against. message is for people and may change. Quote requestId when you contact us.
HTTP statuses
| Status | Codes | Meaning |
|---|---|---|
400 | invalid_request, invalid_amount, idempotency_key_required, invalid_event | The request is malformed or an amount is invalid. |
401 | unauthenticated, invalid_signature | No valid session, or a webhook signature failed. |
403 | forbidden, origin_not_allowed, csrf_failed, verification_required, transfer_blocked | Not allowed for this caller or state. |
404 | not_found | No such resource, or not yours. |
409 | quote_used, not_cancellable, cancel_window_closed, review_required, too_late | The request conflicts with the current state. |
410 | quote_expired | The price is no longer held. |
422 | limit_exceeded, corridor_unavailable, unsupported_country, unsupported_method, fast_unavailable, idempotency_key_reused, quote_source_mismatch | Understood, but not allowed. |
429 | rate_limited, too_many_requests, too_many_attempts, resend_too_soon | Slow down. |
503 | partner_unavailable, compliance_unavailable, delivery_failed | A dependency is unavailable. Safe to retry. |
500 | internal_error | Our fault. Quote the requestId. |
Payout failure codes
Your errors are mapped to a fixed set before they reach customers or logs. Raw provider text, which may contain personal data, is never shown or stored.
| Code | Meaning |
|---|---|
invalid_recipient | The recipient details are not valid. |
recipient_bank_rejected | The recipient's bank refused the payment. |
compliance_hold | Held for a compliance reason. |
quote_expired | Your quote guarantee ended before the payout began. |
provider_unavailable | Your system could not take the request. |
limit_exceeded | A limit on your side was reached. |
unknown | Anything else. Prefer a specific code. |
When you reject a request, say whether it is retryable (try again later), permanent (do not retry), or an authentication problem. Retryable failures are retried with the same idempotency key; permanent failures end the payout and refund the sender.