Anton.Docs
Dashboard (opens in a new tab)
Get started

Error handling

The error object every /v1 response uses, how status and type relate, and every error code the API returns.

Every non-2xx response from /v1 has the same JSON shape, whatever the status. Branch on error.code, not on error.message: messages are written for people and can change, codes are a stable contract.

The error object

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_precision_invalid",
    "message": "CAD amounts allow 2 decimal places; got 3.",
    "param": "amount",
    "doc_url": "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid",
    "request_id": "req_01JD3XB7Q2"
  }
}
FieldTypeAlways presentDescription
error.typestringYesThe broad class of error. It follows the HTTP status. See Types.
error.codestringYesStable, machine-readable, snake_case. Every code is listed in the catalog below, under an anchor with the code's name.
error.messagestringYesA description for a developer. Safe to log. It never contains personal data. A 5xx message is always generic.
error.paramstringNoThe request field or query parameter at fault, when there is one (amount, individual.birth_date).
error.doc_urlstringYesA link to this page at the code's anchor.
error.request_idstringYesOur identifier for the request (req_...). The same value is in the Request-Id response header. Quote it in support requests.
error.detailsarrayNoPresent on validation failures. One entry per failing field, so you can fix a whole form in one pass.

Validation errors

A request that is well formed but fails field validation returns 422 with code: "validation_error" (or a more specific code) and a details array. Each entry has the failing param, a code and a message.

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "validation failed",
    "doc_url": "https://docs.antonpayments.com/api-reference/errors#validation_error",
    "request_id": "req_01JD3XB7Q2",
    "details": [
      { "param": "individual.first_name", "code": "validation_error", "message": "is required" },
      { "param": "destination_currency", "code": "validation_error", "message": "is required" },
      { "param": "individual.birth_date", "code": "validation_error", "message": "must be YYYY-MM-DD" }
    ]
  }
}

param uses dotted paths for nested objects (individual.address.country). Fix every entry before you retry.

Types

The type follows the status, so you can handle a class of error without knowing every code.

TypeStatusMeaning
authentication_error401No credentials, or credentials that do not verify.
permission_error403Valid credentials that lack the permission, scope or capability.
invalid_request_error400, 404, 405, 409, 410, 413, 422The request cannot be completed as sent: malformed (400), no such resource (404), wrong method (405), conflicts with current state (409), retired endpoint (410), too large (413), or fails a business rule (422).
idempotency_error409, 422An Idempotency-Key problem: still in flight (409) or reused with a different body (422). A missing key is a 400 invalid_request_error with the code missing_idempotency_key.
rate_limit_error429You are over a rate limit.
api_error500, 502, 503Something failed on our side or at a provider. Retrying with the same Idempotency-Key is safe.

Statuses

StatusWhen
200Success: read, update, state change. A delete returns the deleted object's id, its object name and "deleted": true.
201A new resource was created.
202Accepted for asynchronous work. The body is the resource in its pending state.
400The request is malformed: JSON, an unknown field or parameter, a type, an ID's shape, a body that is not application/json (invalid_content_type), a missing Idempotency-Key.
401No credentials, or credentials that do not verify. Carries WWW-Authenticate, see Authentication challenge.
403Valid credentials without the permission, scope or capability.
404The resource does not exist for your account.
409The request conflicts with the resource's current state, or an identical request is still in flight.
413The body or upload is larger than the endpoint accepts.
422The request is well formed but fails a business rule.
429Rate limited. Carries Retry-After.
500, 502, 503Our failure, a provider's failure, or temporary unavailability. A 503 carries Retry-After.

Authentication challenge

Every 401 carries a WWW-Authenticate header (RFC 6750, RFC 9449). It names the scheme, the realm and the DPoP proof algorithms the API accepts:

WWW-Authenticate: DPoP realm="anton", algs="ES256 EdDSA"

When you sent a credential and it was refused, the header also names the reason: error="invalid_token" for an access token (or a static API key) that does not verify, and error="invalid_dpop_proof" when the DPoP proof is what failed. A request with no credential carries no error. POST /oauth/token answers a 401 with WWW-Authenticate: Basic realm="anton" and keeps its RFC 6749 body.

Handling errors

  • 4xx: do not retry unchanged. Fix the request (the exceptions are 409 idempotency_in_flight and 429, below).
  • 409 idempotency_in_flight: wait a moment and send the same request again. The completed response is replayed.
  • 429: wait the number of seconds in Retry-After. See Rate limits.
  • 5xx: retry with the same Idempotency-Key and exponential backoff with jitter. If it persists, send us the request_id.
  • Treat a code you do not recognise as the generic case for its type. New codes can be added at any time. See the changelog.

POST /oauth/token is the one exception to this format. It follows RFC 6749 ({"error": "invalid_client", "error_description": "..."}) because OAuth libraries expect it. See Authentication.

Error codes

Codes group below by what went wrong, then run in order of status. The status for each code is fixed.

Request

CodeStatusTypeWhat it means
bad_request400invalid_request_errorThe request body could not be read.
cursor_invalid400invalid_request_errorcursor is not one this endpoint issued, has expired, or has been altered. Start again from the first page.
empty_body400invalid_request_errorThe endpoint needs a JSON body and none was sent.
file_hash_mismatch400invalid_request_errorThe file_hash you sent does not match the uploaded file. Re-upload the file.
ids_required400invalid_request_errorA bulk action was sent with an empty ids list.
invalid_api_version400invalid_request_errorThe Anton-Version header is not a version Anton knows. Send one of the versions in the changelog or omit the header.
invalid_content_type400invalid_request_errorThe request has a body but its Content-Type is not application/json. Upload endpoints (batch upload and beneficiary import) take multipart/form-data instead.
invalid_csv400invalid_request_errorThe CSV could not be parsed. Check the header row and quoting against the template.
invalid_days400invalid_request_errordays is not an integer in the range the endpoint accepts.
invalid_document_id400invalid_request_errorThe document ID is missing.
invalid_file400invalid_request_errorThe uploaded file is empty or could not be read.
invalid_file_format400invalid_request_errorThe uploaded file is not a supported format. Use CSV or XLSX as the endpoint documents.
invalid_limit400invalid_request_errorlimit is not an integer from 1 to 100.
invalid_multipart_form400invalid_request_errorThe upload is not a well-formed multipart/form-data request with a file part.
invalid_owner_id400invalid_request_errorThe owner ID is missing.
invalid_query_param400invalid_request_errorA query parameter has a value the endpoint does not accept. param names it.
invalid_request400invalid_request_errorThe request is malformed in a way no more specific code covers.
invalid_template_format400invalid_request_errorThe template format is not one the endpoint offers.
invalid_template_type400invalid_request_errorThe template type is not one the endpoint offers.
malformed_json400invalid_request_errorThe body is not valid JSON.
missing_idempotency_key400invalid_request_errorA POST that needs an Idempotency-Key header was sent without one. PATCH and DELETE do not need one. See Idempotency.
missing_required_field400invalid_request_errorA required field is missing. param names it.
resource_id_invalid400invalid_request_errorA path ID does not have the shape of an ID for this resource (wrong prefix or characters). param names it. The request cannot name any resource. See resource_missing for a well-formed ID that does not exist.
too_many_ids400invalid_request_errorA bulk action named more IDs than one request may carry.
type_mismatch400invalid_request_errorA field has the wrong JSON type, or an amount is not a valid decimal string. param names it.
unknown_field400invalid_request_errorThe body has a field the endpoint does not define. Unknown fields are rejected, never ignored. param names it.
unknown_parameter400invalid_request_errorThe query string has a parameter the endpoint does not define. param names it.
method_not_allowed405invalid_request_errorThe path exists but does not support this HTTP method.
deprecated_endpoint410invalid_request_errorThe endpoint has been retired. Migrate to its replacement; the Sunset header gave the date.
file_too_large413invalid_request_errorThe uploaded file is larger than the endpoint accepts.
payload_too_large413invalid_request_errorThe body is larger than the endpoint accepts.

Authentication and access

CodeStatusTypeWhat it means
invalid_api_key401authentication_errorThe credential you sent is not a valid API credential. Use OAuth client credentials with DPoP.
invalid_dpop_proof401authentication_errorThe DPoP proof is missing or failed verification (method, URL, iat, jti or key). See Authentication.
invalid_token401authentication_errorThe access token is expired, malformed, or not bound to the DPoP proof you sent.
merchant_context_required401authentication_errorThe endpoint needs a credential tied to a merchant account, and the one you sent is not.
not_authenticated401authentication_errorYou are not signed in. Same meaning as unauthorized.
static_api_keys_disabled401authentication_errorA static API key was sent. Keys are not accepted; use OAuth client credentials with DPoP.
unauthorized401authentication_errorNo credentials, or credentials that do not verify (expired, malformed or revoked). Get a fresh token; see Authentication.
approver_not_independent403permission_errorThe approver is not independent of the person who proposed the action.
approver_required403permission_errorThe action needs an approver, and the credential does not carry that permission.
capability_required403permission_errorYour account does not hold the capability (payouts or intelligence) this endpoint needs.
forbidden403permission_errorA general 403, sent only when no more specific code applies. Permission failures on /v1 use insufficient_permissions.
insufficient_permissions403permission_errorThe credential or signed-in user is not allowed to perform this action.
insufficient_scope403permission_errorThe credential was created without the scope this endpoint needs. Create a credential with the right scope.
key_environment_mismatch403permission_errorA sandbox credential was used against production, or the reverse.
merchant_not_active403permission_errorYour account is not yet active.
merchant_suspended403permission_errorYour account is suspended and cannot perform this action. Contact support.
merchant_terminated403permission_errorYour account is closed and cannot perform this action.
module_not_enabled403permission_errorYour account does not have the add-on this endpoint needs.
not_proposer403permission_errorOnly the person who proposed the action may do this.
sandbox_only403permission_errorThe endpoint is available only in the sandbox.
self_approval_forbidden403permission_errorA person cannot approve their own proposal.

Not found

CodeStatusTypeWhat it means
merchant_not_found404invalid_request_errorThe addressed account does not exist.
not_found404invalid_request_errorNo such resource for your account. A resource that belongs to another account looks the same.
resource_missing404invalid_request_errorA well-formed ID, or a currency, names nothing for your account: it does not exist, or it belongs to another account. The two cases are not told apart.
subject_details_not_stored404invalid_request_errorNo details were kept for this subject.

Conflicts

CodeStatusTypeWhat it means
already_exists409invalid_request_errorA create conflicted with a resource that already exists.
already_monitored409invalid_request_errorThe subject is already being monitored.
approval_ended409invalid_request_errorThe approval has already ended.
batch_confirmation_expired409invalid_request_errorThe validated batch was not confirmed in time. Upload the file again.
batch_not_cancellable409invalid_request_errorThe batch is finished or already processing; cancel its payouts individually.
batch_not_validated409invalid_request_errorThe batch has not finished validating, or failed validation, so it cannot be confirmed.
beneficiary_not_active409invalid_request_errorThe beneficiary is archived or otherwise not active, so it cannot receive payouts or instruments.
conflict409invalid_request_errorA general 409, sent only when no more specific code applies. Known conflicts, such as payout_not_cancellable, have their own code.
decision_not_pending409invalid_request_errorThe decision is no longer pending.
decision_pending409invalid_request_errorThe review already has a decision waiting to be applied.
duplicate_beneficiary409invalid_request_errorAn active beneficiary with the same identifying details already exists.
duplicate_file409invalid_request_errorA batch with this exact file is still being processed.
duplicate_instrument409invalid_request_errorThe beneficiary already has this instrument.
idempotency_in_flight409idempotency_errorAnother request with the same Idempotency-Key is still being processed. Retry after it completes; the completed response is then replayed.
import_already_confirmed409invalid_request_errorThis beneficiary import has already been confirmed.
import_expired409invalid_request_errorThis beneficiary import was not confirmed in time. Upload the file again.
invalid_verification_state409invalid_request_errorThe verification is not in a state where this action applies.
monitoring_limit_reached409invalid_request_errorYour account has reached its limit of monitored subjects.
note_limit_reached409invalid_request_errorThe review already has the most notes it can hold.
payout_not_cancellable409invalid_request_errorThe payout is past the point where it can be cancelled.
payout_on_hold409invalid_request_errorThe payout is on hold, so it cannot be cancelled until the hold ends.
quote_already_used409invalid_request_errorThe quote has already been used for an exchange. Request a new quote.
retention_cannot_decrease409invalid_request_errorRetention can only grow, never shrink.
review_closed409invalid_request_errorThe review is closed and takes no further changes.
review_not_waiting409invalid_request_errorThe review is not paused, so it cannot be resumed.
second_approver_unavailable409invalid_request_errorThe decision needs a second approver and none is available.
webhook_subscription_inactive409invalid_request_errorThe webhook subscription is not active, so a test event cannot be sent.

Business rules

CodeStatusTypeWhat it means
amount_invalid422invalid_request_errorThe amount is zero or negative. Amounts must be greater than zero; param names the field.
amount_precision_invalid422invalid_request_errorThe amount has more decimal places than the currency allows. GET /v1/currencies lists each currency's precision.
api_version_downgrade422invalid_request_errorThe Anton-Version you asked for is older than the version your account is pinned to. Pinned versions only move forward.
batch_cancel_failed422invalid_request_errorThe batch could not be cancelled. Safe to retry.
batch_confirm_failed422invalid_request_errorThe batch could not be confirmed. Safe to retry with the same key.
batch_upload_failed422invalid_request_errorThe upload could not be stored. Safe to retry with a new key.
beneficiary_archive_failed422invalid_request_errorThe beneficiary could not be archived. Retry, and contact support with the request_id if it persists.
beneficiary_delete_failed422invalid_request_errorThe beneficiary could not be deleted. Retry, and contact support with the request_id if it persists.
beneficiary_pii_update_failed422invalid_request_errorThe beneficiary's personal details could not be updated. Retry, and contact support with the request_id if it persists.
beneficiary_restore_failed422invalid_request_errorThe beneficiary could not be restored. Retry, and contact support with the request_id if it persists.
beneficiary_update_failed422invalid_request_errorThe beneficiary could not be updated. Retry, and contact support with the request_id if it persists.
cannot_be_processed422invalid_request_errorWe could not process this request. Contact support with the request_id.
case_file_too_large422invalid_request_errorThe case file is too large to export.
country_not_supported422invalid_request_errorThe destination country is not enabled for your account or for this payment method.
currency_not_supported422invalid_request_errorThe currency or asset is not supported for this operation.
export_too_large422invalid_request_errorThe export would exceed the row limit. Narrow the date range.
idempotency_key_reused422idempotency_errorThe Idempotency-Key was already used with a different request body. Send a new key for a new request.
import_confirm_failed422invalid_request_errorThe beneficiary import could not be confirmed. Safe to retry with the same key.
import_preview_failed422invalid_request_errorThe beneficiary import could not be previewed. Upload the file again.
import_too_large422invalid_request_errorThe import file has more rows than one import may hold.
instrument_delete_failed422invalid_request_errorThe instrument could not be deleted. Retry, and contact support with the request_id if it persists.
instrument_update_failed422invalid_request_errorThe instrument could not be updated. Retry, and contact support with the request_id if it persists.
insufficient_balance422invalid_request_errorYour available balance cannot cover the amount. Fund the account and retry with a new key.
invalid_country_code422invalid_request_errorThe country is not a supported ISO 3166-1 alpha-2 code.
invalid_credentials422invalid_request_errorCreating an instrument: the account details for its method failed validation, such as a card number, CLABE, CBU or IBAN in the wrong format. message names the field.
invalid_decision422invalid_request_errorThe review decision is not allowed in the review's current state.
invalid_display_name422invalid_request_errordisplay_name is missing.
invalid_email422invalid_request_erroremail is missing or malformed.
invalid_export_range422invalid_request_errorThe export date range is invalid or too wide.
422invalid_request_errorlink_expires_in_days must be 7, 14 or 30.
invalid_message422invalid_request_errormessage is too long.
invalid_reason_code422invalid_request_errorThe reason code is not accepted with this decision.
invalid_subject_type422invalid_request_errortype must be person or business.
422invalid_request_errorThe linked evaluation or review does not exist.
method_not_supported422invalid_request_errorThe payment method is not available for this destination.
no_buy_account422invalid_request_errorYou have no account in the currency you are buying.
no_funding_account422invalid_request_errorYou have no account in the funding currency.
note_too_long422invalid_request_errorThe note is longer than 2,000 characters.
owner_not_eligible422invalid_request_errorThe owner is not able to decide reviews.
payout_rejected422invalid_request_errorThe payout was refused. The payout's status_message says what to correct.
policy_blocked422invalid_request_errorOnly on POST /v1/payouts: one of your own approval policies with action block matched, and no payout was created. The policy.matched webhook names the policy.
pricing_plan_not_found422invalid_request_errorNo pricing plan applies to this request.
quote_expired422invalid_request_errorThe quote has expired. Request a new one.
quote_mismatch422invalid_request_errorThe request does not match the quote it names.
quote_not_locked422invalid_request_errorThe quote is an indicative one and cannot be executed. Request a locked quote.
reference_not_allowed422invalid_request_errorThe reference holds content it must not, such as a card number.
unsupported_sandbox_currency422invalid_request_errorSandbox deposits are available only for the currencies the endpoint lists.
validation_error422invalid_request_errorOne or more fields failed validation. details lists every failing field.

Rate limits

CodeStatusTypeWhat it means
export_busy429rate_limit_errorAnother export is already running. Retry shortly. Retry-After says how many seconds to wait.
rate_limit_exceeded429rate_limit_errorYou exceeded a rate limit. Retry-After says how many seconds to wait. See Rate limits.
rate_limited429rate_limit_errorYou exceeded a rate limit. Same meaning as rate_limit_exceeded; Retry-After says how many seconds to wait.
rate_limited_sandbox_deposit429rate_limit_errorToo many sandbox deposits. Retry-After says how many seconds to wait.

Server and upstream

CodeStatusTypeWhat it means
fx_execution_failed500api_errorThe exchange could not be executed. Retry with the same Idempotency-Key, and quote the request_id if it persists.
internal_error500api_errorSomething failed on our side. The message is generic. Retry with the same Idempotency-Key, and quote the request_id if it persists.
sandbox_deposit_failed500api_errorThe sandbox credit could not be applied. Retry with a new key.
fx_rates_unavailable502api_errorFX rates are temporarily unavailable. Retry shortly.
upstream_error502api_errorA provider we depend on failed. Retry with the same Idempotency-Key.
auth_unavailable503api_errorAuthentication is temporarily unavailable. Retry with backoff.
case_lookup_unavailable503api_errorThe lookup for this beneficiary's review cases is temporarily unavailable. Retry with backoff.
export_unavailable503api_errorExports are temporarily unavailable. Retry with backoff.
fx_unavailable503api_errorExchanges are temporarily unavailable. Retry with backoff.
idempotency_unavailable503api_errorThe idempotency check is temporarily unavailable. Retry with the same key.
locked_rate_unavailable503api_errorA locked rate could not be provided right now. Retry shortly.
notes_unavailable503api_errorNotes cannot be stored right now. Retry with backoff.
oauth_unavailable503api_errorOAuth authentication is temporarily unavailable. Retry with backoff.
sandbox_seeder_unavailable503api_errorSandbox funding is not available right now. Retry with backoff.
screening_unavailable503api_errorScreening is temporarily unavailable. Retry with backoff.
service_unavailable503api_errorThe service is temporarily unavailable. Retry with backoff.
subject_storage_unavailable503api_errorSubject details cannot be stored right now. Retry with backoff.
temporarily_unavailable503api_errorThis could not be completed right now. Retry in a moment.
verification_not_configured503api_errorVerification is not available for your account.

Webhook URL checks

A webhook subscription's url is checked when you create or update it. These come back as 400 with param set to url.

CodeStatusTypeWhat it means
webhook_url_invalid400invalid_request_errorThe url is not a valid URL.
webhook_url_not_https400invalid_request_errorThe url does not use https.
webhook_url_private_address400invalid_request_errorThe url is not publicly reachable. Use an HTTPS endpoint on the public internet.
webhook_url_required400invalid_request_errorThe url is missing.

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗