Errors
The error envelope, how to branch on it, when to retry, and the codes you will meet most.
The error envelope
Every error, whatever refused the request, answers with the same JSON body and an HTTP status in the 4xx or 5xx range:
{
"code": "quote_expired",
"message": "the Quote has expired; ask for a new decision",
"correlation_id": "b2d4f6a8-1c3e-4a5b-9d7f-0e2c4a6b8d1f"
}| Field | Type | Meaning |
|---|---|---|
code | string | A stable, snake_case code. Branch on it. |
message | string | A sentence for people. It may change; never parse it. |
correlation_id | string | The request's id in our logs. Also in the X-Correlation-ID header. Quote it to support. |
details | array | Present on some errors, such as validation_failed: one {field, message} per problem. |
Branch on the code
Decide what to do from code. The HTTP status tells you the class of problem; the code tells you which one. New codes can appear, so keep a default branch that treats an unknown code by its status.
const res = await fetch(url, options);
if (!res.ok) {
const err = await res.json();
switch (err.code) {
case "quote_expired":
return requote();
case "rate_limited":
return retryAfter(Number(res.headers.get("Retry-After") ?? "1"));
default:
throw new Error(`${res.status} ${err.code} (correlation ${err.correlation_id})`);
}
}A 5xx never carries the cause in message: it reads internal error or a generic status text. The code still names the failure where one is known (for example quote_unavailable), and the correlation_id lets us find the cause.
Validation errors
A body that fails its field rules answers 400 with validation_failed and one entry per field, named as you sent it:
{
"code": "validation_failed",
"message": "request validation failed",
"correlation_id": "9e1c3a5b-7d2f-4e8a-b6c4-1f3d5a7b9c2e",
"details": [
{ "field": "beneficiary_id", "message": "failed on the 'uuid' rule" },
{ "field": "purpose", "message": "failed on the 'oneof' rule" }
]
}A body that is not valid JSON, or that has a value of the wrong JSON type (an amount sent as a number instead of a string), answers 400 with bad_request and no details.
Retrying
| What happened | What to do |
|---|---|
429 rate_limited | Wait the seconds in Retry-After, then retry. |
500, 502, 503, or a timeout with no answer | Retry with exponential backoff. For POST /v1/payouts and POST /v1/end-customers, send the same Idempotency-Key and the same body. |
409 idempotency_in_progress | The first request with that key is still running. Retry in a second or two. |
422 quote_expired | Ask for new Quotes and accept one of them. |
Any other 4xx | Fix the request. Sending it again unchanged gets the same answer. |
Requests other than the two above take no Idempotency-Key. Before you retry one of them after a timeout, read the resource to see whether the first attempt went through. See Idempotency.
Codes you will meet most
| Status | Code | When |
|---|---|---|
| 400 | validation_failed | A field breaks its rules; see details. |
| 400 | bad_request | The body is not valid JSON or a value has the wrong type. |
| 400 | invalid_id | A path id is not a UUID. |
| 400 | idempotency_key_required | POST /v1/payouts or POST /v1/end-customers without an Idempotency-Key. |
| 401 | unauthorized | No credential, or one that is not an API key. |
| 401 | api_key_invalid | The key is unknown, malformed, revoked or from the other environment. |
| 401 | api_key_expired | The key has expired. |
| 401 | api_key_ip_denied | The request came from an address the key does not allow. |
| 403 | forbidden | The key lacks the permission this route needs. |
| 403 | customer_suspended | Your account is suspended; changes are refused, reads work. |
| 403 | customer_not_active | Your account is not active. |
| 404 | not_found | No such route. Check the method and path. |
| 404 | payout_not_found | No Payout of yours has this id. |
| 404 | beneficiary_not_found | No Beneficiary of yours has this id. |
| 409 | quote_already_used | This Quote already became a Payout. Read your Payouts, or ask for new Quotes. |
| 409 | payout_not_cancellable | Only an accepted or awaiting_approval Payout can be cancelled. |
| 409 | idempotency_in_progress | A request with the same Idempotency-Key is still running. |
| 409 | beneficiary_changed | The Customer you pay changed its receiving account after the quote. Quote again. |
| 409 | beneficiary_unavailable | The Beneficiary cannot be paid now. |
| 422 | quote_expired | The Quote's expires_at has passed. |
| 422 | quote_token_invalid | The quote_id is not one you were given. |
| 422 | idempotency_key_reused | The Idempotency-Key was used with a different body. |
| 422 | bad_amount | The amount is not a positive decimal string. |
| 422 | amount_scale | The amount has more decimals than its asset allows. |
| 422 | beneficiary_not_verified | The Beneficiary is not verified yet. |
| 422 | iban_invalid | The IBAN fails its check digits. |
| 422 | beneficiary_fields_invalid | The details include a field no route to that destination asks for. |
| 422 | bad_cursor, bad_limit, unknown_state | A list query parameter is wrong. |
| 422 | webhook_url_invalid | The URL is not https on the public internet, or carries credentials. |
| 429 | rate_limited | Too many requests; see Retry-After. |
| 500 | internal_error | Something failed on our side. Retry with backoff. |
| 502 | quote_unavailable | A Provider could not price a Leg just now. Ask again shortly. |
| 503 | service_unavailable | A dependency is down for a moment. Retry with backoff. |
All error codes
| Code | HTTP status | Message | Operations |
|---|---|---|---|
bad_request | 400 | Bad Request | |
document_file_required | 400 | the upload must carry a file part named file | |
idempotency_key_invalid | 400 | Idempotency-Key must be between 1 and 128 characters | Every operation |
idempotency_key_required | 400 | Idempotency-Key header is required | Every operation |
invalid_id | 400 | id is not a UUID. | |
validation_failed | 400 | request validation failed | |
api_key_expired | 401 | the API key has expired | Every operation |
api_key_invalid | 401 | the API key is not valid | Every operation |
api_key_ip_denied | 401 | the API key may not be used from this address | Every operation |
api_key_revoked | 401 | the API key has been revoked | Every operation |
unauthorized | 401 | Unauthorized | Every operation |
customer_not_active | 403 | the Customer cannot be used yet | Every operation |
customer_suspended | 403 | the Customer is suspended; nothing can be changed until it is reactivated | Every operation |
forbidden | 403 | Forbidden | Every operation |
not_a_platform | 403 | only a Platform has End Customers | |
not_for_end_customers | 403 | an End Customer's Platform holds its API keys and webhook endpoints | Every operation |
people_only | 403 | only a person can invite someone; an API key cannot | |
suspended_by_operator | 403 | the Operator suspended this End Customer; only the Operator can reactivate it | |
beneficiary_not_found | 404 | no Beneficiary under that id for the Customer | |
decision_not_found | 404 | The quote set behind quote_id no longer exists; ask for a new Quote. | |
document_not_found | 404 | no document under that id for the Customer | |
end_customer_not_found | 404 | no End Customer of yours under that id | listBalanceslistBeneficiariescreateBeneficiarylinkBeneficiarygetBeneficiarygetCustomerlistDepositInstructionslistDocumentsuploadDocumentdownloadDocumentlistEndCustomerscreateEndCustomergetEndCustomerreactivateEndCustomersuspendEndCustomerlistIncomingPayoutsgetIncomingPayoutgetOnboardinglistPayoutscreatePayoutgetPayoutcancelPayoutgetProfilesaveProfilesubmitProfilecreateQuotegetReceivingsetReceivingAccountissueReceivingCodegetTermsacceptTermslistWebhookEndpointscreateWebhookEndpointredeliverWebhooklistWebhookDeliveriesdisableWebhookEndpointenableWebhookEndpointrotateWebhookSecret |
payout_not_found | 404 | no Payout under that id | |
quote_not_found | 404 | the Decision Record holds no Quote for that Route Template | |
receiving_code_not_found | 404 | no Customer receives under that code | |
webhook_delivery_not_found | 404 | webhook delivery not found | |
webhook_endpoint_not_found | 404 | webhook endpoint not found | |
beneficiary_changed | 409 | the Beneficiary's account changed after the quote; quote again | |
beneficiary_unavailable | 409 | the Beneficiary cannot be paid now; its Customer has no account to receive into | |
customer_email_taken | 409 | a Customer of this Operating Entity already uses that email | |
idempotency_in_progress | 409 | a request with this Idempotency-Key is still being processed | Every operation |
invalid_transition | 409 | Depends on the operation; hover one to see what it means there. | |
payout_not_cancellable | 409 | a Payout can be cancelled only before it is funded | |
profile_locked | 409 | Depends on the operation; hover one to see what it means there. | |
quote_already_used | 409 | this quote has already been accepted | |
receiving_account_missing | 409 | the Customer behind that code has no Receiving Account yet | |
terms_changed | 409 | the terms changed after they were read | |
terms_not_accepted | 409 | the terms have not been accepted | |
webhook_delivery_pending | 409 | the delivery is still being attempted | |
webhook_endpoint_state | 409 | the webhook endpoint is not in a state that allows this | |
document_too_large | 413 | a document may be at most 10 MB | |
payload_too_large | 413 | Request Entity Too Large | |
amount_scale | 422 | amount has more decimals than the asset settles at | |
asset_invalid | 422 | asset is required: an asset code of 2 to 10 capital letters or digits | |
bad_amount | 422 | amount is not a positive decimal number. | |
bad_cursor | 422 | the cursor is not one a Payout list answered | |
bad_limit | 422 | Depends on the operation; hover one to see what it means there. | |
beneficiary_fields_invalid | 422 | the Beneficiary carries details no Rail to that destination asks for | |
beneficiary_not_verified | 422 | the Beneficiary is not verified | |
cannot_link_self | 422 | that is the Customer's own Receiving Code | |
country_mismatch | 422 | the address in the profile is not in the country this account was opened for | |
country_not_accepted | 422 | Depends on the operation; hover one to see what it means there. | |
customer_not_active | 422 | the Customer is not active | |
document_empty | 422 | the file is empty | |
document_kind_unknown | 422 | unknown document kind | |
document_limit_reached | 422 | the Customer holds as many documents as it may; versions are never deleted | |
document_subject_invalid | 422 | the document's subject does not fit its kind or the Customer | |
document_type_not_allowed | 422 | a document must be a PDF, JPEG or PNG file | |
iban_invalid | 422 | the IBAN does not check out | |
idempotency_key_reused | 422 | Idempotency-Key was already used with a different request | Every operation |
linked_customer_not_active | 422 | a Beneficiary of the customer kind links an active Customer of the same Operating Entity | |
profile_invalid | 422 | the Compliance Profile is incomplete | |
profile_missing | 422 | save a Compliance Profile before submitting it | |
proof_required | 422 | an own account needs a proof of ownership before it is verified | |
quote_expired | 422 | the Quote has expired; ask for a new decision | |
quote_inconsistent | 422 | the Quote and the Route Template it names no longer agree | |
quote_token_invalid | 422 | the quote_id is not one this Customer was quoted | |
receiving_account_invalid | 422 | a Receiving Account is one of the Customer's own accounts that Compliance verified | |
unknown_state | 422 | Depends on the operation; hover one to see what it means there. | |
webhook_endpoint_limit | 422 | the Customer already has the most webhook endpoints it may register | |
webhook_event_unknown | 422 | an event type is not one a webhook endpoint can subscribe to | |
webhook_url_invalid | 422 | the url must be an https address on the public internet, without credentials | |
rate_limited | 429 | Too Many Requests | Every operation |
internal_error | 500 | internal error | Every operation |
bad_gateway | 502 | Bad Gateway | Every operation |
policy_unavailable | 502 | internal error | |
prerequisites_unavailable | 502 | internal error | |
quote_unavailable | 502 | internal error | |
approval_rules_unavailable | 503 | internal error | |
beneficiaries_unavailable | 503 | internal error | |
customers_unavailable | 503 | internal error | |
document_busy | 503 | internal error | |
float_unavailable | 503 | internal error | |
funds_unavailable | 503 | internal error | |
pricing_unavailable | 503 | internal error | |
webhooks_unavailable | 503 | internal error |