Skip to Content
Apex Settlement

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:

422 Unprocessable Entity
{
  "code": "quote_expired",
  "message": "the Quote has expired; ask for a new decision",
  "correlation_id": "b2d4f6a8-1c3e-4a5b-9d7f-0e2c4a6b8d1f"
}
FieldTypeMeaning
codestringA stable, snake_case code. Branch on it.
messagestringA sentence for people. It may change; never parse it.
correlation_idstringThe request's id in our logs. Also in the X-Correlation-ID header. Quote it to support.
detailsarrayPresent 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.

Node.js
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:

400 Bad Request
{
  "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 happenedWhat to do
429 rate_limitedWait the seconds in Retry-After, then retry.
500, 502, 503, or a timeout with no answerRetry with exponential backoff. For POST /v1/payouts and POST /v1/end-customers, send the same Idempotency-Key and the same body.
409 idempotency_in_progressThe first request with that key is still running. Retry in a second or two.
422 quote_expiredAsk for new Quotes and accept one of them.
Any other 4xxFix 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

StatusCodeWhen
400validation_failedA field breaks its rules; see details.
400bad_requestThe body is not valid JSON or a value has the wrong type.
400invalid_idA path id is not a UUID.
400idempotency_key_requiredPOST /v1/payouts or POST /v1/end-customers without an Idempotency-Key.
401unauthorizedNo credential, or one that is not an API key.
401api_key_invalidThe key is unknown, malformed, revoked or from the other environment.
401api_key_expiredThe key has expired.
401api_key_ip_deniedThe request came from an address the key does not allow.
403forbiddenThe key lacks the permission this route needs.
403customer_suspendedYour account is suspended; changes are refused, reads work.
403customer_not_activeYour account is not active.
404not_foundNo such route. Check the method and path.
404payout_not_foundNo Payout of yours has this id.
404beneficiary_not_foundNo Beneficiary of yours has this id.
409quote_already_usedThis Quote already became a Payout. Read your Payouts, or ask for new Quotes.
409payout_not_cancellableOnly an accepted or awaiting_approval Payout can be cancelled.
409idempotency_in_progressA request with the same Idempotency-Key is still running.
409beneficiary_changedThe Customer you pay changed its receiving account after the quote. Quote again.
409beneficiary_unavailableThe Beneficiary cannot be paid now.
422quote_expiredThe Quote's expires_at has passed.
422quote_token_invalidThe quote_id is not one you were given.
422idempotency_key_reusedThe Idempotency-Key was used with a different body.
422bad_amountThe amount is not a positive decimal string.
422amount_scaleThe amount has more decimals than its asset allows.
422beneficiary_not_verifiedThe Beneficiary is not verified yet.
422iban_invalidThe IBAN fails its check digits.
422beneficiary_fields_invalidThe details include a field no route to that destination asks for.
422bad_cursor, bad_limit, unknown_stateA list query parameter is wrong.
422webhook_url_invalidThe URL is not https on the public internet, or carries credentials.
429rate_limitedToo many requests; see Retry-After.
500internal_errorSomething failed on our side. Retry with backoff.
502quote_unavailableA Provider could not price a Leg just now. Ask again shortly.
503service_unavailableA dependency is down for a moment. Retry with backoff.

All error codes

86 codes
CodeHTTP statusMessageOperations
bad_request400Bad Request
document_file_required400the upload must carry a file part named file
idempotency_key_invalid400Idempotency-Key must be between 1 and 128 characters
Every operation
idempotency_key_required400Idempotency-Key header is required
Every operation
invalid_id400id is not a UUID.
validation_failed400request validation failed
api_key_expired401the API key has expired
Every operation
api_key_invalid401the API key is not valid
Every operation
api_key_ip_denied401the API key may not be used from this address
Every operation
api_key_revoked401the API key has been revoked
Every operation
unauthorized401Unauthorized
Every operation
customer_not_active403the Customer cannot be used yet
Every operation
customer_suspended403the Customer is suspended; nothing can be changed until it is reactivated
Every operation
forbidden403Forbidden
Every operation
not_a_platform403only a Platform has End Customers
not_for_end_customers403an End Customer's Platform holds its API keys and webhook endpoints
Every operation
people_only403only a person can invite someone; an API key cannot
suspended_by_operator403the Operator suspended this End Customer; only the Operator can reactivate it
beneficiary_not_found404no Beneficiary under that id for the Customer
decision_not_found404The quote set behind quote_id no longer exists; ask for a new Quote.
document_not_found404no document under that id for the Customer
end_customer_not_found404no End Customer of yours under that id
payout_not_found404no Payout under that id
quote_not_found404the Decision Record holds no Quote for that Route Template
receiving_code_not_found404no Customer receives under that code
webhook_delivery_not_found404webhook delivery not found
webhook_endpoint_not_found404webhook endpoint not found
beneficiary_changed409the Beneficiary's account changed after the quote; quote again
beneficiary_unavailable409the Beneficiary cannot be paid now; its Customer has no account to receive into
customer_email_taken409a Customer of this Operating Entity already uses that email
idempotency_in_progress409a request with this Idempotency-Key is still being processed
Every operation
invalid_transition409Depends on the operation; hover one to see what it means there.
payout_not_cancellable409a Payout can be cancelled only before it is funded
profile_locked409Depends on the operation; hover one to see what it means there.
quote_already_used409this quote has already been accepted
receiving_account_missing409the Customer behind that code has no Receiving Account yet
terms_changed409the terms changed after they were read
terms_not_accepted409the terms have not been accepted
webhook_delivery_pending409the delivery is still being attempted
webhook_endpoint_state409the webhook endpoint is not in a state that allows this
document_too_large413a document may be at most 10 MB
payload_too_large413Request Entity Too Large
amount_scale422amount has more decimals than the asset settles at
asset_invalid422asset is required: an asset code of 2 to 10 capital letters or digits
bad_amount422amount is not a positive decimal number.
bad_cursor422the cursor is not one a Payout list answered
bad_limit422Depends on the operation; hover one to see what it means there.
beneficiary_fields_invalid422the Beneficiary carries details no Rail to that destination asks for
beneficiary_not_verified422the Beneficiary is not verified
country_mismatch422the address in the profile is not in the country this account was opened for
country_not_accepted422Depends on the operation; hover one to see what it means there.
customer_not_active422the Customer is not active
document_empty422the file is empty
document_kind_unknown422unknown document kind
document_limit_reached422the Customer holds as many documents as it may; versions are never deleted
document_subject_invalid422the document's subject does not fit its kind or the Customer
document_type_not_allowed422a document must be a PDF, JPEG or PNG file
iban_invalid422the IBAN does not check out
idempotency_key_reused422Idempotency-Key was already used with a different request
Every operation
linked_customer_not_active422a Beneficiary of the customer kind links an active Customer of the same Operating Entity
profile_invalid422the Compliance Profile is incomplete
profile_missing422save a Compliance Profile before submitting it
proof_required422an own account needs a proof of ownership before it is verified
quote_expired422the Quote has expired; ask for a new decision
quote_inconsistent422the Quote and the Route Template it names no longer agree
quote_token_invalid422the quote_id is not one this Customer was quoted
receiving_account_invalid422a Receiving Account is one of the Customer's own accounts that Compliance verified
unknown_state422Depends on the operation; hover one to see what it means there.
webhook_endpoint_limit422the Customer already has the most webhook endpoints it may register
webhook_event_unknown422an event type is not one a webhook endpoint can subscribe to
webhook_url_invalid422the url must be an https address on the public internet, without credentials
rate_limited429Too Many Requests
Every operation
internal_error500internal error
Every operation
bad_gateway502Bad Gateway
Every operation
policy_unavailable502internal error
prerequisites_unavailable502internal error
quote_unavailable502internal error
approval_rules_unavailable503internal error
beneficiaries_unavailable503internal error
customers_unavailable503internal error
document_busy503internal error
float_unavailable503internal error
funds_unavailable503internal error
pricing_unavailable503internal error
webhooks_unavailable503internal error

On this page