Error codes - Atum Docs

Atum returns 54 public error codes. Every Payment Gateway HTTP error response carries a docs_url pointing at the entry for its code on this page. This list is generated from the error catalog the services emit from, and is regenerated whenever that catalog changes, so it cannot fall behind the codes you actually receive.

Branch on code. It is the stable, machine-readable field. message is curated text and two responses sharing a code can carry different text.

Response shape

Payment Gateway HTTP errors return this body. code and message are always present. The rest are included when they apply. The example below is a real catalog entry, not an invented one. The x402 facilitator reports failures in the x402 envelope instead, using isValid/invalidReason or success/errorReason.

{
  "code": "SETTLEMENT_FAILED",
  "message": "We couldn't complete the settlement for this payment. The on-chain outcome is not guaranteed, so reconcile by payment id before retrying.",
  "request_id": "req_123456789",
  "payment_id": "0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c",
  "docs_url": "https://docs.atum.xyz/errors#settlement-failed",
  "retry_classification": "RECONCILE_THEN_DECIDE"
}

An asynchronous payment failure appears as the error object on GET /v1/payments/{payment_id}/status instead. It carries the same code plus blockchain_context, but no docs_url, request_id or retry_classification.

string

What to do next. Absent means the condition has not been classified, which is not the same as safe to retry. Re-sending the same request_id is an idempotent replay and always safe. This field is about submitting a new one, which starts a new payment.

string

The originating service domain, one of ten values. Absent when the error did not come from a service that sets it.

Retry after a delay

RETRY_AFTER_DELAY: no payment was created and the condition is transient, so re-send the same request_id after a delay.

Code	HTTP
`AUTHORIZATION_UNAVAILABLE`	503
`SERVICE_PAUSED`	503
`TRANSACTION_NOT_FOUND`	400
`VERIFICATION_TIMEOUT`	400

Reconcile before deciding

RECONCILE_THEN_DECIDE: the outcome is not known. Check the payment before issuing a new request_id, or you may pay twice. Only meaningful alongside a payment_id, since you cannot reconcile a payment you cannot name.

Code	HTTP
`CONFLICT`	409
`COUNTERPARTY_TIMEOUT`	504
`DUPLICATE_INTENT`	409
`PAYMENT_EXPIRED`	404
`SETTLEMENT_FAILED`	502
`SETTLEMENT_OUTCOME_UNKNOWN`	500
`WEBHOOK_CONNECTION_ERROR`	502
`WEBHOOK_ERROR`	502

Retry with a new request id

RETRY_WITH_NEW_IDENTIFIER: terminal, and no settlement was ever awarded for it, so a fresh request_id is safe to submit.

Code	HTTP
`IDEMPOTENCY_TERMS_MISMATCH`	409
`NO_QUOTES_RECEIVED`	422
`QUOTES_EXPIRED`	422
`REQUEST_ID_TAKEN`	409

Poll for completion

POLL_FOR_COMPLETION: the operation is still running. Poll its status. Do not submit a new request_id until it is terminal, and do not re-send this one expecting a different answer.

Code	HTTP
`EVENT_NOT_FOUND`	425
`INSUFFICIENT_CONFIRMATIONS`	400
`PAYMENT_IN_PROGRESS`	409

Fix the request

NOT_RETRYABLE_FIX_REQUEST: the request itself is wrong. Fix it and re-send. Whether the same request_id may be reused is answered by request_id_reusable, not by this value: an unserved corridor is also a fix-the-request condition and it does spend the id.

Code	HTTP
`AMOUNT_MISMATCH`	400
`COUNTERPARTY_NOT_FOUND`	404
`FORBIDDEN`	403
`FULFILLMENT_DEADLINE_NOT_FUTURE`	400
`FULFILLMENT_DEADLINE_ORDER`	400
`INVALID_DESTINATION_ACCOUNT`	400
`INVALID_DESTINATION_ASSET`	400
`INVALID_FULFILLMENT_AMOUNT`	400
`INVALID_REQUEST`	400
`INVALID_REQUEST_ID`	400
`INVALID_SOURCE_ACCOUNT`	400
`INVALID_SOURCE_ASSET`	400
`MALFORMED_REQUEST_BODY`	400
`METHOD_NOT_ALLOWED`	405
`MISSING_DESTINATION`	400
`MISSING_REQUEST_ID_PARAM`	400
`MISSING_SENDER_AUTH`	400
`NO_SETTLER_FOR_CORRIDOR`	422
`NOT_FOUND`	404
`PAYLOAD_TOO_LARGE`	413
`PAYMENT_ID_DERIVATION_FAILED`	400
`QUOTE_DEADLINE_NOT_FUTURE`	400
`SENDER_AUTH_NOT_ALLOWED`	400
`UNAUTHENTICATED`	401
`UNSUPPORTED_DESTINATION_ASSET`	400
`UNSUPPORTED_DESTINATION_CHAIN`	400
`UNSUPPORTED_SOURCE_ASSET`	400
`UNSUPPORTED_SOURCE_CHAIN`	400

Already done

ALREADY_DONE: the operation had already completed. Read its current state rather than submitting anything.

Code	HTTP
`ALREADY_SETTLED`	409

Contact support

CONTACT_SUPPORT: not resolvable by the caller. Quote request_id.

Code	HTTP
`AUTHORIZATION_DECLINED`	403
`NOT_IMPLEMENTED`	501
`SIGNATURE_GENERATION_FAILED`	500
`VERIFICATION_FAILED`	400

Depends on the condition

Each of these public codes covers several conditions that do not share one answer, so the value differs per response. Branch on the retry_classification you actually received, not on the code alone.

Code	HTTP
`INTERNAL_ERROR`	500
`SERVICE_BUSY`	503

Reference

ALREADY_SETTLED

HTTP 409. Retry classification ALREADY_DONE.

This payment has already settled. Read its status rather than submitting it again.

AMOUNT_MISMATCH

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The on-chain amount does not match the expected amount.

AUTHORIZATION_DECLINED

HTTP 403. Retry classification CONTACT_SUPPORT.

This payment was declined during authorization. The reason is not included in this response.

AUTHORIZATION_UNAVAILABLE

HTTP 503. Retry classification RETRY_AFTER_DELAY.

This payment could not be authorized because a check could not be completed. It was not declined.

CONFLICT

HTTP 409. Retry classification RECONCILE_THEN_DECIDE.

The request conflicts with the current state of the resource.

COUNTERPARTY_NOT_FOUND

HTTP 404. Retry classification NOT_RETRYABLE_FIX_REQUEST.

No counterparty is registered to authorize this payment.

COUNTERPARTY_TIMEOUT

HTTP 504. Retry classification RECONCILE_THEN_DECIDE.

The counterparty did not respond within the timeout window.

DUPLICATE_INTENT

HTTP 409. Retry classification RECONCILE_THEN_DECIDE. This code covers more than one condition, so message differs between responses. Branch on code, never on the text.

This request duplicates a payment that is already being processed. The outcome of that payment is not guaranteed, so reconcile by payment id before retrying.

This request duplicates an already-processed payment. The on-chain outcome is not guaranteed, so reconcile by payment id before retrying.

EVENT_NOT_FOUND

HTTP 425. Retry classification POLL_FOR_COMPLETION.

No matching on-chain event has been observed yet.

FORBIDDEN

HTTP 403. Retry classification NOT_RETRYABLE_FIX_REQUEST.

You do not have permission to perform this action.

FULFILLMENT_DEADLINE_NOT_FUTURE

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

fulfillment_deadline must be a timestamp in the future.

FULFILLMENT_DEADLINE_ORDER

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

fulfillment_deadline must be after quote_deadline.

IDEMPOTENCY_TERMS_MISMATCH

HTTP 409. Retry classification RETRY_WITH_NEW_IDENTIFIER.

This request_id was already used for a different request (accounts, assets, or amounts differ). Re-submitting a request_id retries the original, so each new request needs its own request_id.

INSUFFICIENT_CONFIRMATIONS

HTTP 400. Retry classification POLL_FOR_COMPLETION.

The transaction does not yet have enough confirmations.

INTERNAL_ERROR

HTTP 500. Retry classification varies by condition: CONTACT_SUPPORT, RETRY_AFTER_DELAY. Some conditions carry none. This code covers more than one condition, so message differs between responses. Branch on code, never on the text.

Fulfillment verification is temporarily unavailable for this chain.

Something went wrong on our side. Quote the request id if you contact support, and check the payment before submitting a new request.

Something went wrong on our side. Quote the request id if you contact support.

INVALID_DESTINATION_ACCOUNT

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

A destination account is not a payable address on its destination chain. It must parse for that chain, carry a valid EIP-55 checksum when mixed-case, have no surrounding whitespace, and not be the zero address.

INVALID_DESTINATION_ASSET

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

A destination asset identifier is not a valid CAIP-19 asset.

INVALID_FULFILLMENT_AMOUNT

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

fulfillment_amount must be a positive integer in the asset smallest unit.

INVALID_REQUEST

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST. This code covers more than one condition, so message differs between responses. Branch on code, never on the text.

An amount in this request is not valid. It must be a positive integer expressed in the chain’s smallest unit.

The request was malformed or missing required fields.

INVALID_REQUEST_ID

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

request_id may contain only letters, digits, underscore, hyphen, and dot.

INVALID_SOURCE_ACCOUNT

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

source.account is required and must not be empty or padded with whitespace.

INVALID_SOURCE_ASSET

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The source asset identifier is not a valid CAIP-19 asset.

MALFORMED_REQUEST_BODY

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The request body could not be read or did not match the required schema. Check the JSON and required fields.

METHOD_NOT_ALLOWED

HTTP 405. Retry classification NOT_RETRYABLE_FIX_REQUEST.

That HTTP method is not allowed on this path. The path exists, so check the method rather than the URL.

MISSING_DESTINATION

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

At least one destination is required.

MISSING_REQUEST_ID_PARAM

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The request_id query parameter is required.

MISSING_SENDER_AUTH

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

sender_auth is required for this endpoint.

NO_QUOTES_RECEIVED

HTTP 422. Retry classification RETRY_WITH_NEW_IDENTIFIER.

No settlement quotes were received within the auction window. This request_id is spent, so a new attempt needs a new one.

NO_SETTLER_FOR_CORRIDOR

HTTP 422. Retry classification NOT_RETRYABLE_FIX_REQUEST.

No settlement provider currently serves this source and destination pair. This request_id is spent, so a new attempt needs a new one, and it will not succeed until a provider covers the pair.

NOT_FOUND

HTTP 404. Retry classification NOT_RETRYABLE_FIX_REQUEST. This code covers more than one condition, so message differs between responses. Branch on code, never on the text.

The requested chain is not supported.

The requested resource was not found.

NOT_IMPLEMENTED

HTTP 501. Retry classification CONTACT_SUPPORT.

This operation is not available yet.

PAYLOAD_TOO_LARGE

HTTP 413. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The request body is too large.

PAYMENT_EXPIRED

HTTP 404. Retry classification RECONCILE_THEN_DECIDE.

This payment has expired and is no longer available.

PAYMENT_ID_DERIVATION_FAILED

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The payment could not be identified from the request. Check sender_auth and its signed message.

PAYMENT_IN_PROGRESS

HTTP 409. Retry classification POLL_FOR_COMPLETION.

This payment is still being processed. Poll its status until it reaches a terminal state rather than submitting again.

QUOTE_DEADLINE_NOT_FUTURE

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

quote_deadline must be a timestamp in the future.

QUOTES_EXPIRED

HTTP 422. Retry classification RETRY_WITH_NEW_IDENTIFIER.

No settlement quote could be selected for this payment. Either the quotes received had expired by the award moment, or none was acceptable. This request_id is spent, so a new attempt needs a new one.

REQUEST_ID_TAKEN

HTTP 409. Retry classification RETRY_WITH_NEW_IDENTIFIER.

This request_id is already in use by another account. Submit this payment with a new request_id.

SENDER_AUTH_NOT_ALLOWED

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

sender_auth must be omitted on a quote request. It is supplied at award time.

SERVICE_BUSY

HTTP 503. Retry classification varies by condition: RETRY_AFTER_DELAY, RETRY_WITH_NEW_IDENTIFIER. This code covers more than one condition, so message differs between responses. Branch on code, never on the text.

No capacity was available to start an auction for this payment. This request_id is spent, so a new attempt needs a new one.

The service is temporarily busy.

SERVICE_PAUSED

HTTP 503. Retry classification RETRY_AFTER_DELAY.

This operation is temporarily paused. Nothing was signed or submitted for this request.

SETTLEMENT_FAILED

HTTP 502. Retry classification RECONCILE_THEN_DECIDE.

We couldn’t complete the settlement for this payment. The on-chain outcome is not guaranteed, so reconcile by payment id before retrying.

SETTLEMENT_OUTCOME_UNKNOWN

HTTP 500. Retry classification RECONCILE_THEN_DECIDE.

Something went wrong on our side after settlement had started, so we cannot confirm whether funds moved. Reconcile this payment by payment id before submitting a new request.

SIGNATURE_GENERATION_FAILED

HTTP 500. Retry classification CONTACT_SUPPORT.

Signing failed for this request.

TRANSACTION_NOT_FOUND

HTTP 400. Retry classification RETRY_AFTER_DELAY.

The transaction could not be found on-chain.

UNAUTHENTICATED

HTTP 401. Retry classification NOT_RETRYABLE_FIX_REQUEST.

Authentication is required, or the provided credentials are invalid.

UNSUPPORTED_DESTINATION_ASSET

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

A destination asset is not a supported token on its chain, so no settler can be offered this payment.

UNSUPPORTED_DESTINATION_CHAIN

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

A destination chain is not supported.

UNSUPPORTED_SOURCE_ASSET

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The source asset is not a supported token on its chain, so no settler can be offered this payment.

UNSUPPORTED_SOURCE_CHAIN

HTTP 400. Retry classification NOT_RETRYABLE_FIX_REQUEST.

The source chain is not supported.

VERIFICATION_FAILED

HTTP 400. Retry classification CONTACT_SUPPORT.

On-chain verification could not be completed.

VERIFICATION_TIMEOUT

HTTP 400. Retry classification RETRY_AFTER_DELAY.

On-chain verification timed out before a result was available.

WEBHOOK_CONNECTION_ERROR

HTTP 502. Retry classification RECONCILE_THEN_DECIDE.

The counterparty could not be reached.

WEBHOOK_ERROR

HTTP 502. Retry classification RECONCILE_THEN_DECIDE.

The counterparty’s webhook returned an unexpected status while processing this authorization. That is not a decline, and it does not tell us whether they acted on the request.

Troubleshooting

Diagnose a payment that failed or stalled.

Reconciliation

Confirm an outcome before retrying, so you don’t pay twice.

Decline reasons

Why one settlement provider did not quote, which is not a payment failure.

​Response shape

​Retry after a delay

​Reconcile before deciding

​Retry with a new request id

​Poll for completion

​Fix the request

​Already done

​Contact support

​Depends on the condition

​Reference

​ALREADY_SETTLED

​AMOUNT_MISMATCH

​AUTHORIZATION_DECLINED

​AUTHORIZATION_UNAVAILABLE

​CONFLICT

​COUNTERPARTY_NOT_FOUND

​COUNTERPARTY_TIMEOUT

​DUPLICATE_INTENT

​EVENT_NOT_FOUND

​FORBIDDEN

​FULFILLMENT_DEADLINE_NOT_FUTURE

​FULFILLMENT_DEADLINE_ORDER

​IDEMPOTENCY_TERMS_MISMATCH

​INSUFFICIENT_CONFIRMATIONS

​INTERNAL_ERROR

​INVALID_DESTINATION_ACCOUNT

​INVALID_DESTINATION_ASSET

​INVALID_FULFILLMENT_AMOUNT

​INVALID_REQUEST

​INVALID_REQUEST_ID

​INVALID_SOURCE_ACCOUNT

​INVALID_SOURCE_ASSET

​MALFORMED_REQUEST_BODY

​METHOD_NOT_ALLOWED

​MISSING_DESTINATION

​MISSING_REQUEST_ID_PARAM

​MISSING_SENDER_AUTH

​NO_QUOTES_RECEIVED

​NO_SETTLER_FOR_CORRIDOR

​NOT_FOUND

​NOT_IMPLEMENTED

​PAYLOAD_TOO_LARGE

​PAYMENT_EXPIRED

​PAYMENT_ID_DERIVATION_FAILED

​PAYMENT_IN_PROGRESS

​QUOTE_DEADLINE_NOT_FUTURE

​QUOTES_EXPIRED

​REQUEST_ID_TAKEN

​SENDER_AUTH_NOT_ALLOWED

​SERVICE_BUSY

​SERVICE_PAUSED

​SETTLEMENT_FAILED

​SETTLEMENT_OUTCOME_UNKNOWN

​SIGNATURE_GENERATION_FAILED

​TRANSACTION_NOT_FOUND

​UNAUTHENTICATED

​UNSUPPORTED_DESTINATION_ASSET

​UNSUPPORTED_DESTINATION_CHAIN

​UNSUPPORTED_SOURCE_ASSET

​UNSUPPORTED_SOURCE_CHAIN

​VERIFICATION_FAILED

​VERIFICATION_TIMEOUT

​WEBHOOK_CONNECTION_ERROR

​WEBHOOK_ERROR

Troubleshooting

Reconciliation

Decline reasons

Response shape

Retry after a delay

Reconcile before deciding

Retry with a new request id

Poll for completion

Fix the request

Already done

Contact support

Depends on the condition

Reference

ALREADY_SETTLED

AMOUNT_MISMATCH

AUTHORIZATION_DECLINED

AUTHORIZATION_UNAVAILABLE

CONFLICT

COUNTERPARTY_NOT_FOUND

COUNTERPARTY_TIMEOUT

DUPLICATE_INTENT

EVENT_NOT_FOUND

FORBIDDEN

FULFILLMENT_DEADLINE_NOT_FUTURE

FULFILLMENT_DEADLINE_ORDER

IDEMPOTENCY_TERMS_MISMATCH

INSUFFICIENT_CONFIRMATIONS

INTERNAL_ERROR

INVALID_DESTINATION_ACCOUNT

INVALID_DESTINATION_ASSET

INVALID_FULFILLMENT_AMOUNT

INVALID_REQUEST

INVALID_REQUEST_ID

INVALID_SOURCE_ACCOUNT

INVALID_SOURCE_ASSET

MALFORMED_REQUEST_BODY

METHOD_NOT_ALLOWED

MISSING_DESTINATION

MISSING_REQUEST_ID_PARAM

MISSING_SENDER_AUTH

NO_QUOTES_RECEIVED

NO_SETTLER_FOR_CORRIDOR

NOT_FOUND

NOT_IMPLEMENTED

PAYLOAD_TOO_LARGE

PAYMENT_EXPIRED

PAYMENT_ID_DERIVATION_FAILED

PAYMENT_IN_PROGRESS

QUOTE_DEADLINE_NOT_FUTURE

QUOTES_EXPIRED

REQUEST_ID_TAKEN

SENDER_AUTH_NOT_ALLOWED

SERVICE_BUSY

SERVICE_PAUSED

SETTLEMENT_FAILED

SETTLEMENT_OUTCOME_UNKNOWN

SIGNATURE_GENERATION_FAILED

TRANSACTION_NOT_FOUND

UNAUTHENTICATED

UNSUPPORTED_DESTINATION_ASSET

UNSUPPORTED_DESTINATION_CHAIN

UNSUPPORTED_SOURCE_ASSET

UNSUPPORTED_SOURCE_CHAIN

VERIFICATION_FAILED

VERIFICATION_TIMEOUT

WEBHOOK_CONNECTION_ERROR

WEBHOOK_ERROR