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.
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.
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.
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.
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.
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.
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.
Already done
ALREADY_DONE: the operation had already completed. Read its current state rather than submitting anything.
Contact support
CONTACT_SUPPORT: not resolvable by the caller. Quote request_id.
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 theretry_classification you actually received, not on the code alone.
Reference
ALREADY_SETTLED
HTTP 409. Retry classificationALREADY_DONE.
This payment has already settled. Read its status rather than submitting it again.
AMOUNT_MISMATCH
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The on-chain amount does not match the expected amount.
AUTHORIZATION_DECLINED
HTTP 403. Retry classificationCONTACT_SUPPORT.
This payment was declined during authorization. The reason is not included in this response.
AUTHORIZATION_UNAVAILABLE
HTTP 503. Retry classificationRETRY_AFTER_DELAY.
This payment could not be authorized because a check could not be completed. It was not declined.
CHALLENGE_EXPIRED
HTTP 401. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The nonce or challenge in this presentation has expired or was not issued by this service. Sign a new presentation over a new one.
CHALLENGE_REPLAYED
HTTP 401. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The nonce or challenge in this presentation was already used. Each one is accepted at most once, including by an attempt that was refused.
CONFLICT
HTTP 409. Retry classificationRECONCILE_THEN_DECIDE.
The request conflicts with the current state of the resource.
COUNTERPARTY_NOT_FOUND
HTTP 404. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
No counterparty is registered to authorize this payment.
COUNTERPARTY_TIMEOUT
HTTP 504. Retry classificationRECONCILE_THEN_DECIDE.
The counterparty did not respond within the timeout window.
CREDENTIAL_MISSING
HTTP 403. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The presentation does not include a credential this endpoint requires, issued to the presentation’s holder.
CREDENTIAL_UNTRUSTED
HTTP 403. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
A credential in the presentation was not issued by an issuer this service trusts.
DUPLICATE_INTENT
HTTP 409. Retry classificationRECONCILE_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 classificationPOLL_FOR_COMPLETION.
No matching on-chain event has been observed yet.
FORBIDDEN
HTTP 403. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
You do not have permission to perform this action.
FULFILLMENT_DEADLINE_NOT_FUTURE
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
fulfillment_deadline must be a timestamp in the future.
FULFILLMENT_DEADLINE_ORDER
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
fulfillment_deadline must be after quote_deadline.
IDEMPOTENCY_TERMS_MISMATCH
HTTP 409. Retry classificationRETRY_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.
IDENTITY_DENYLISTED
HTTP 403. Retry classificationCONTACT_SUPPORT.
This identity is not permitted to authenticate. The reason is not included in this response.
INSUFFICIENT_CONFIRMATIONS
HTTP 400. Retry classificationPOLL_FOR_COMPLETION.
The transaction does not yet have enough confirmations.
INSUFFICIENT_FUNDS
HTTP 422. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The paying account held less of the source token than this payment needs, so the deposit could not be funded and no funds were moved.
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 classificationNOT_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 classificationNOT_RETRYABLE_FIX_REQUEST.
A destination asset identifier is not a valid CAIP-19 asset.
INVALID_ESCROW_CONTRACT_ADDRESS
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
escrow_contract_address is required and must be the escrow served by /v1/defaults for the source chain.
INVALID_FULFILLMENT_AMOUNT
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
fulfillment_amount must be a positive integer in the asset smallest unit.
INVALID_FULFILLMENT_VERIFIER
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
fulfillment_verifier is required, with a non-empty account and an absolute endpoint URL. Use the value served by /v1/defaults.
INVALID_PRESENTATION
HTTP 401. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The presentation could not be verified. It must be signed by its holder over the issued nonce or challenge and the expected domain.
INVALID_REQUEST
HTTP 400. Retry classificationNOT_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 classificationNOT_RETRYABLE_FIX_REQUEST.
request_id may contain only letters, digits, underscore, hyphen, and dot.
INVALID_SOURCE_ACCOUNT
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
source.account is required and must not be empty or padded with whitespace.
INVALID_SOURCE_ASSET
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The source asset identifier is not a valid CAIP-19 asset.
MALFORMED_REQUEST_BODY
HTTP 400. Retry classificationNOT_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 classificationNOT_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 classificationNOT_RETRYABLE_FIX_REQUEST.
At least one destination is required.
MISSING_MESSAGE_PREHASH
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
Every sender_auth signed message must carry its message_prehash.
MISSING_REQUEST_ID_PARAM
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The request_id query parameter is required.
MISSING_SENDER_AUTH
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
sender_auth is required for this endpoint.
MISSING_TOKEN_APPROVAL
HTTP 422. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The paying account had not approved the Permit2 contract to transfer enough of the source token, so the deposit could not be funded and no funds were moved.
NO_QUOTES_RECEIVED
HTTP 422. Retry classificationRETRY_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 classificationNOT_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 classificationNOT_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 classificationCONTACT_SUPPORT.
This operation is not available yet.
PAYLOAD_TOO_LARGE
HTTP 413. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The request body is too large.
PAYMENT_EXPIRED
HTTP 404. Retry classificationRECONCILE_THEN_DECIDE.
This payment has expired and is no longer available.
PAYMENT_ID_DERIVATION_FAILED
HTTP 400. Retry classificationNOT_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 classificationPOLL_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 classificationNOT_RETRYABLE_FIX_REQUEST.
quote_deadline must be a timestamp in the future.
QUOTES_EXPIRED
HTTP 422. Retry classificationRETRY_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.
RATE_LIMIT_EXCEEDED
HTTP 429. Retry classificationRETRY_AFTER_DELAY.
Too many requests from this caller, or too many unused nonces outstanding. Wait before trying again.
REQUEST_ID_TAKEN
HTTP 409. Retry classificationRETRY_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 classificationNOT_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 classificationRETRY_AFTER_DELAY.
This operation is temporarily paused. Nothing was signed or submitted for this request.
SETTLEMENT_FAILED
HTTP 502. Retry classificationRECONCILE_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 classificationRECONCILE_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 classificationCONTACT_SUPPORT.
Signing failed for this request.
TOKEN_EXPIRED
HTTP 401. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
The session token has expired, was not issued by this service, or is past the session’s time limit. Sign a new presentation to start a new session.
TRANSACTION_NOT_FOUND
HTTP 400. Retry classificationRETRY_AFTER_DELAY.
The transaction could not be found on-chain.
UNAUTHENTICATED
HTTP 401. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
Authentication is required, or the provided credentials are invalid.
UNSUPPORTED_DESTINATION_ASSET
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
A destination asset is not a supported token on its chain, or the payment gives fulfill to the originator and the destination token does not implement EIP-3009 transferWithAuthorization. No settler can be offered this payment.
UNSUPPORTED_DESTINATION_CHAIN
HTTP 400. Retry classificationNOT_RETRYABLE_FIX_REQUEST.
A destination chain is not supported.
UNSUPPORTED_SOURCE_ASSET
HTTP 400. Retry classificationNOT_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 classificationNOT_RETRYABLE_FIX_REQUEST.
The source chain is not supported.
VERDICT_ALREADY_FINAL
HTTP 409. Retry classificationALREADY_DONE.
The opposite outcome for this payment was already authorized and is final. Read the payment’s status rather than asking again.
VERIFICATION_FAILED
HTTP 400. Retry classificationCONTACT_SUPPORT.
On-chain verification could not be completed.
VERIFICATION_TIMEOUT
HTTP 400. Retry classificationRETRY_AFTER_DELAY.
On-chain verification timed out before a result was available.
WEBHOOK_CONNECTION_ERROR
HTTP 502. Retry classificationRECONCILE_THEN_DECIDE.
The counterparty could not be reached.
WEBHOOK_ERROR
HTTP 502. Retry classificationRECONCILE_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.