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
{
"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"
}
}| Field | Type | Always present | Description |
|---|---|---|---|
error.type | string | Yes | The broad class of error. It follows the HTTP status. See Types. |
error.code | string | Yes | Stable, machine-readable, snake_case. Every code is listed in the catalog below, under an anchor with the code's name. |
error.message | string | Yes | A description for a developer. Safe to log. It never contains personal data. A 5xx message is always generic. |
error.param | string | No | The request field or query parameter at fault, when there is one (amount, individual.birth_date). |
error.doc_url | string | Yes | A link to this page at the code's anchor. |
error.request_id | string | Yes | Our identifier for the request (req_...). The same value is in the Request-Id response header. Quote it in support requests. |
error.details | array | No | Present 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.
{
"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.
| Type | Status | Meaning |
|---|---|---|
authentication_error | 401 | No credentials, or credentials that do not verify. |
permission_error | 403 | Valid credentials that lack the permission, scope or capability. |
invalid_request_error | 400, 404, 405, 409, 410, 413, 422 | The 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_error | 409, 422 | An 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_error | 429 | You are over a rate limit. |
api_error | 500, 502, 503 | Something failed on our side or at a provider. Retrying with the same Idempotency-Key is safe. |
Statuses
| Status | When |
|---|---|
200 | Success: read, update, state change. A delete returns the deleted object's id, its object name and "deleted": true. |
201 | A new resource was created. |
202 | Accepted for asynchronous work. The body is the resource in its pending state. |
400 | The 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. |
401 | No credentials, or credentials that do not verify. Carries WWW-Authenticate, see Authentication challenge. |
403 | Valid credentials without the permission, scope or capability. |
404 | The resource does not exist for your account. |
409 | The request conflicts with the resource's current state, or an identical request is still in flight. |
413 | The body or upload is larger than the endpoint accepts. |
422 | The request is well formed but fails a business rule. |
429 | Rate limited. Carries Retry-After. |
500, 502, 503 | Our 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 are409 idempotency_in_flightand429, 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 inRetry-After. See Rate limits.5xx: retry with the sameIdempotency-Keyand exponential backoff with jitter. If it persists, send us therequest_id.- Treat a
codeyou do not recognise as the generic case for itstype. 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
| Code | Status | Type | What it means |
|---|---|---|---|
bad_request | 400 | invalid_request_error | The request body could not be read. |
cursor_invalid | 400 | invalid_request_error | cursor is not one this endpoint issued, has expired, or has been altered. Start again from the first page. |
empty_body | 400 | invalid_request_error | The endpoint needs a JSON body and none was sent. |
file_hash_mismatch | 400 | invalid_request_error | The file_hash you sent does not match the uploaded file. Re-upload the file. |
ids_required | 400 | invalid_request_error | A bulk action was sent with an empty ids list. |
invalid_api_version | 400 | invalid_request_error | The Anton-Version header is not a version Anton knows. Send one of the versions in the changelog or omit the header. |
invalid_content_type | 400 | invalid_request_error | The 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_csv | 400 | invalid_request_error | The CSV could not be parsed. Check the header row and quoting against the template. |
invalid_days | 400 | invalid_request_error | days is not an integer in the range the endpoint accepts. |
invalid_document_id | 400 | invalid_request_error | The document ID is missing. |
invalid_file | 400 | invalid_request_error | The uploaded file is empty or could not be read. |
invalid_file_format | 400 | invalid_request_error | The uploaded file is not a supported format. Use CSV or XLSX as the endpoint documents. |
invalid_limit | 400 | invalid_request_error | limit is not an integer from 1 to 100. |
invalid_multipart_form | 400 | invalid_request_error | The upload is not a well-formed multipart/form-data request with a file part. |
invalid_owner_id | 400 | invalid_request_error | The owner ID is missing. |
invalid_query_param | 400 | invalid_request_error | A query parameter has a value the endpoint does not accept. param names it. |
invalid_request | 400 | invalid_request_error | The request is malformed in a way no more specific code covers. |
invalid_template_format | 400 | invalid_request_error | The template format is not one the endpoint offers. |
invalid_template_type | 400 | invalid_request_error | The template type is not one the endpoint offers. |
malformed_json | 400 | invalid_request_error | The body is not valid JSON. |
missing_idempotency_key | 400 | invalid_request_error | A POST that needs an Idempotency-Key header was sent without one. PATCH and DELETE do not need one. See Idempotency. |
missing_required_field | 400 | invalid_request_error | A required field is missing. param names it. |
resource_id_invalid | 400 | invalid_request_error | A 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_ids | 400 | invalid_request_error | A bulk action named more IDs than one request may carry. |
type_mismatch | 400 | invalid_request_error | A field has the wrong JSON type, or an amount is not a valid decimal string. param names it. |
unknown_field | 400 | invalid_request_error | The body has a field the endpoint does not define. Unknown fields are rejected, never ignored. param names it. |
unknown_parameter | 400 | invalid_request_error | The query string has a parameter the endpoint does not define. param names it. |
method_not_allowed | 405 | invalid_request_error | The path exists but does not support this HTTP method. |
deprecated_endpoint | 410 | invalid_request_error | The endpoint has been retired. Migrate to its replacement; the Sunset header gave the date. |
file_too_large | 413 | invalid_request_error | The uploaded file is larger than the endpoint accepts. |
payload_too_large | 413 | invalid_request_error | The body is larger than the endpoint accepts. |
Authentication and access
| Code | Status | Type | What it means |
|---|---|---|---|
invalid_api_key | 401 | authentication_error | The credential you sent is not a valid API credential. Use OAuth client credentials with DPoP. |
invalid_dpop_proof | 401 | authentication_error | The DPoP proof is missing or failed verification (method, URL, iat, jti or key). See Authentication. |
invalid_token | 401 | authentication_error | The access token is expired, malformed, or not bound to the DPoP proof you sent. |
merchant_context_required | 401 | authentication_error | The endpoint needs a credential tied to a merchant account, and the one you sent is not. |
not_authenticated | 401 | authentication_error | You are not signed in. Same meaning as unauthorized. |
static_api_keys_disabled | 401 | authentication_error | A static API key was sent. Keys are not accepted; use OAuth client credentials with DPoP. |
unauthorized | 401 | authentication_error | No credentials, or credentials that do not verify (expired, malformed or revoked). Get a fresh token; see Authentication. |
approver_not_independent | 403 | permission_error | The approver is not independent of the person who proposed the action. |
approver_required | 403 | permission_error | The action needs an approver, and the credential does not carry that permission. |
capability_required | 403 | permission_error | Your account does not hold the capability (payouts or intelligence) this endpoint needs. |
forbidden | 403 | permission_error | A general 403, sent only when no more specific code applies. Permission failures on /v1 use insufficient_permissions. |
insufficient_permissions | 403 | permission_error | The credential or signed-in user is not allowed to perform this action. |
insufficient_scope | 403 | permission_error | The credential was created without the scope this endpoint needs. Create a credential with the right scope. |
key_environment_mismatch | 403 | permission_error | A sandbox credential was used against production, or the reverse. |
merchant_not_active | 403 | permission_error | Your account is not yet active. |
merchant_suspended | 403 | permission_error | Your account is suspended and cannot perform this action. Contact support. |
merchant_terminated | 403 | permission_error | Your account is closed and cannot perform this action. |
module_not_enabled | 403 | permission_error | Your account does not have the add-on this endpoint needs. |
not_proposer | 403 | permission_error | Only the person who proposed the action may do this. |
sandbox_only | 403 | permission_error | The endpoint is available only in the sandbox. |
self_approval_forbidden | 403 | permission_error | A person cannot approve their own proposal. |
Not found
| Code | Status | Type | What it means |
|---|---|---|---|
merchant_not_found | 404 | invalid_request_error | The addressed account does not exist. |
not_found | 404 | invalid_request_error | No such resource for your account. A resource that belongs to another account looks the same. |
resource_missing | 404 | invalid_request_error | A 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_stored | 404 | invalid_request_error | No details were kept for this subject. |
Conflicts
| Code | Status | Type | What it means |
|---|---|---|---|
already_exists | 409 | invalid_request_error | A create conflicted with a resource that already exists. |
already_monitored | 409 | invalid_request_error | The subject is already being monitored. |
approval_ended | 409 | invalid_request_error | The approval has already ended. |
batch_confirmation_expired | 409 | invalid_request_error | The validated batch was not confirmed in time. Upload the file again. |
batch_not_cancellable | 409 | invalid_request_error | The batch is finished or already processing; cancel its payouts individually. |
batch_not_validated | 409 | invalid_request_error | The batch has not finished validating, or failed validation, so it cannot be confirmed. |
beneficiary_not_active | 409 | invalid_request_error | The beneficiary is archived or otherwise not active, so it cannot receive payouts or instruments. |
conflict | 409 | invalid_request_error | A general 409, sent only when no more specific code applies. Known conflicts, such as payout_not_cancellable, have their own code. |
decision_not_pending | 409 | invalid_request_error | The decision is no longer pending. |
decision_pending | 409 | invalid_request_error | The review already has a decision waiting to be applied. |
duplicate_beneficiary | 409 | invalid_request_error | An active beneficiary with the same identifying details already exists. |
duplicate_file | 409 | invalid_request_error | A batch with this exact file is still being processed. |
duplicate_instrument | 409 | invalid_request_error | The beneficiary already has this instrument. |
idempotency_in_flight | 409 | idempotency_error | Another request with the same Idempotency-Key is still being processed. Retry after it completes; the completed response is then replayed. |
import_already_confirmed | 409 | invalid_request_error | This beneficiary import has already been confirmed. |
import_expired | 409 | invalid_request_error | This beneficiary import was not confirmed in time. Upload the file again. |
invalid_verification_state | 409 | invalid_request_error | The verification is not in a state where this action applies. |
monitoring_limit_reached | 409 | invalid_request_error | Your account has reached its limit of monitored subjects. |
note_limit_reached | 409 | invalid_request_error | The review already has the most notes it can hold. |
payout_not_cancellable | 409 | invalid_request_error | The payout is past the point where it can be cancelled. |
payout_on_hold | 409 | invalid_request_error | The payout is on hold, so it cannot be cancelled until the hold ends. |
quote_already_used | 409 | invalid_request_error | The quote has already been used for an exchange. Request a new quote. |
retention_cannot_decrease | 409 | invalid_request_error | Retention can only grow, never shrink. |
review_closed | 409 | invalid_request_error | The review is closed and takes no further changes. |
review_not_waiting | 409 | invalid_request_error | The review is not paused, so it cannot be resumed. |
second_approver_unavailable | 409 | invalid_request_error | The decision needs a second approver and none is available. |
webhook_subscription_inactive | 409 | invalid_request_error | The webhook subscription is not active, so a test event cannot be sent. |
Business rules
| Code | Status | Type | What it means |
|---|---|---|---|
amount_invalid | 422 | invalid_request_error | The amount is zero or negative. Amounts must be greater than zero; param names the field. |
amount_precision_invalid | 422 | invalid_request_error | The amount has more decimal places than the currency allows. GET /v1/currencies lists each currency's precision. |
api_version_downgrade | 422 | invalid_request_error | The Anton-Version you asked for is older than the version your account is pinned to. Pinned versions only move forward. |
batch_cancel_failed | 422 | invalid_request_error | The batch could not be cancelled. Safe to retry. |
batch_confirm_failed | 422 | invalid_request_error | The batch could not be confirmed. Safe to retry with the same key. |
batch_upload_failed | 422 | invalid_request_error | The upload could not be stored. Safe to retry with a new key. |
beneficiary_archive_failed | 422 | invalid_request_error | The beneficiary could not be archived. Retry, and contact support with the request_id if it persists. |
beneficiary_delete_failed | 422 | invalid_request_error | The beneficiary could not be deleted. Retry, and contact support with the request_id if it persists. |
beneficiary_pii_update_failed | 422 | invalid_request_error | The beneficiary's personal details could not be updated. Retry, and contact support with the request_id if it persists. |
beneficiary_restore_failed | 422 | invalid_request_error | The beneficiary could not be restored. Retry, and contact support with the request_id if it persists. |
beneficiary_update_failed | 422 | invalid_request_error | The beneficiary could not be updated. Retry, and contact support with the request_id if it persists. |
| cannot_be_processed | 422 | invalid_request_error | We could not process this request. Contact support with the request_id. |
case_file_too_large | 422 | invalid_request_error | The case file is too large to export. |
country_not_supported | 422 | invalid_request_error | The destination country is not enabled for your account or for this payment method. |
currency_not_supported | 422 | invalid_request_error | The currency or asset is not supported for this operation. |
export_too_large | 422 | invalid_request_error | The export would exceed the row limit. Narrow the date range. |
idempotency_key_reused | 422 | idempotency_error | The Idempotency-Key was already used with a different request body. Send a new key for a new request. |
import_confirm_failed | 422 | invalid_request_error | The beneficiary import could not be confirmed. Safe to retry with the same key. |
import_preview_failed | 422 | invalid_request_error | The beneficiary import could not be previewed. Upload the file again. |
import_too_large | 422 | invalid_request_error | The import file has more rows than one import may hold. |
instrument_delete_failed | 422 | invalid_request_error | The instrument could not be deleted. Retry, and contact support with the request_id if it persists. |
instrument_update_failed | 422 | invalid_request_error | The instrument could not be updated. Retry, and contact support with the request_id if it persists. |
insufficient_balance | 422 | invalid_request_error | Your available balance cannot cover the amount. Fund the account and retry with a new key. |
invalid_country_code | 422 | invalid_request_error | The country is not a supported ISO 3166-1 alpha-2 code. |
invalid_credentials | 422 | invalid_request_error | Creating 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_decision | 422 | invalid_request_error | The review decision is not allowed in the review's current state. |
invalid_display_name | 422 | invalid_request_error | display_name is missing. |
invalid_email | 422 | invalid_request_error | email is missing or malformed. |
invalid_export_range | 422 | invalid_request_error | The export date range is invalid or too wide. |
invalid_link_expiry | 422 | invalid_request_error | link_expires_in_days must be 7, 14 or 30. |
invalid_message | 422 | invalid_request_error | message is too long. |
invalid_reason_code | 422 | invalid_request_error | The reason code is not accepted with this decision. |
invalid_subject_type | 422 | invalid_request_error | type must be person or business. |
link_not_found | 422 | invalid_request_error | The linked evaluation or review does not exist. |
method_not_supported | 422 | invalid_request_error | The payment method is not available for this destination. |
no_buy_account | 422 | invalid_request_error | You have no account in the currency you are buying. |
no_funding_account | 422 | invalid_request_error | You have no account in the funding currency. |
note_too_long | 422 | invalid_request_error | The note is longer than 2,000 characters. |
owner_not_eligible | 422 | invalid_request_error | The owner is not able to decide reviews. |
payout_rejected | 422 | invalid_request_error | The payout was refused. The payout's status_message says what to correct. |
policy_blocked | 422 | invalid_request_error | Only 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_found | 422 | invalid_request_error | No pricing plan applies to this request. |
quote_expired | 422 | invalid_request_error | The quote has expired. Request a new one. |
quote_mismatch | 422 | invalid_request_error | The request does not match the quote it names. |
quote_not_locked | 422 | invalid_request_error | The quote is an indicative one and cannot be executed. Request a locked quote. |
reference_not_allowed | 422 | invalid_request_error | The reference holds content it must not, such as a card number. |
unsupported_sandbox_currency | 422 | invalid_request_error | Sandbox deposits are available only for the currencies the endpoint lists. |
validation_error | 422 | invalid_request_error | One or more fields failed validation. details lists every failing field. |
Rate limits
| Code | Status | Type | What it means |
|---|---|---|---|
export_busy | 429 | rate_limit_error | Another export is already running. Retry shortly. Retry-After says how many seconds to wait. |
rate_limit_exceeded | 429 | rate_limit_error | You exceeded a rate limit. Retry-After says how many seconds to wait. See Rate limits. |
rate_limited | 429 | rate_limit_error | You exceeded a rate limit. Same meaning as rate_limit_exceeded; Retry-After says how many seconds to wait. |
rate_limited_sandbox_deposit | 429 | rate_limit_error | Too many sandbox deposits. Retry-After says how many seconds to wait. |
Server and upstream
| Code | Status | Type | What it means |
|---|---|---|---|
fx_execution_failed | 500 | api_error | The exchange could not be executed. Retry with the same Idempotency-Key, and quote the request_id if it persists. |
internal_error | 500 | api_error | Something failed on our side. The message is generic. Retry with the same Idempotency-Key, and quote the request_id if it persists. |
sandbox_deposit_failed | 500 | api_error | The sandbox credit could not be applied. Retry with a new key. |
fx_rates_unavailable | 502 | api_error | FX rates are temporarily unavailable. Retry shortly. |
upstream_error | 502 | api_error | A provider we depend on failed. Retry with the same Idempotency-Key. |
auth_unavailable | 503 | api_error | Authentication is temporarily unavailable. Retry with backoff. |
case_lookup_unavailable | 503 | api_error | The lookup for this beneficiary's review cases is temporarily unavailable. Retry with backoff. |
export_unavailable | 503 | api_error | Exports are temporarily unavailable. Retry with backoff. |
fx_unavailable | 503 | api_error | Exchanges are temporarily unavailable. Retry with backoff. |
idempotency_unavailable | 503 | api_error | The idempotency check is temporarily unavailable. Retry with the same key. |
locked_rate_unavailable | 503 | api_error | A locked rate could not be provided right now. Retry shortly. |
notes_unavailable | 503 | api_error | Notes cannot be stored right now. Retry with backoff. |
oauth_unavailable | 503 | api_error | OAuth authentication is temporarily unavailable. Retry with backoff. |
sandbox_seeder_unavailable | 503 | api_error | Sandbox funding is not available right now. Retry with backoff. |
screening_unavailable | 503 | api_error | Screening is temporarily unavailable. Retry with backoff. |
service_unavailable | 503 | api_error | The service is temporarily unavailable. Retry with backoff. |
subject_storage_unavailable | 503 | api_error | Subject details cannot be stored right now. Retry with backoff. |
temporarily_unavailable | 503 | api_error | This could not be completed right now. Retry in a moment. |
verification_not_configured | 503 | api_error | Verification 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.
| Code | Status | Type | What it means |
|---|---|---|---|
webhook_url_invalid | 400 | invalid_request_error | The url is not a valid URL. |
webhook_url_not_https | 400 | invalid_request_error | The url does not use https. |
webhook_url_private_address | 400 | invalid_request_error | The url is not publicly reachable. Use an HTTPS endpoint on the public internet. |
webhook_url_required | 400 | invalid_request_error | The url is missing. |