Errors

The x402 API uses real HTTP status codes. Every error has the same JSON body, and retry_action tells your agent what to do next.

Error body

Name	Type	Description
error	String	Error code, see the table below
message	String	Short human-readable message
retryable	Boolean	Whether repeating can help
retry_action	String	What to do: `resign`, `retry_same_payment`, `poll`, `wait_and_retry`, `abandon`, `human_required`
retry_after_seconds	Integer	When to retry; equals the `Retry-After` header
payment_state	String	`unused`, `in_flight` or `settled` — whether the funds were taken (Retries and idempotency)
authorization_expires_at	String	Until when your authorization can still be executed; do not sign a new one before
order_id, operation_id, poll_url	String	The order and the operation the payment belongs to, when they exist
bound_wallet	String	`quote_bound_to_other_wallet`: the wallet that holds the quote
facilitator_reason	String	Reason of a payment check failure, from a fixed list, or `unknown`
detail	String	Details, for example the path of the invalid field: `/items/0/qty: …`

Responses with a new quote (quote_expired, payment_expired, quote_bound_to_other_wallet) also contain the quote fields and the PAYMENT-REQUIRED header.

{
    "error": "payment_not_settleable",
    "message": "The presented authorization can still be settled",
    "retryable": true,
    "retry_action": "wait_and_retry",
    "retry_after_seconds": 512,
    "payment_state": "unused",
    "authorization_expires_at": "2026-11-02T10:16:00Z"
}

Retry actions

retry_action	What to do
`resign`	Sign the new requirements from this response (`PAYMENT-REQUIRED`), or fix the request
`retry_same_payment`	Send the same request with the same `PAYMENT-SIGNATURE`. Do not sign a new one
`poll`	In `202` responses: poll `poll_url`
`wait_and_retry`	Start over (new quote, new signature) not earlier than `retry_after_seconds`
`abandon`	Repeating the same request will not help
`human_required`	Contact support. Do not sign a new authorization

Error codes

error	HTTP	retry_action	When
`payment_required`	402	`resign`	A paid endpoint was called without `PAYMENT-SIGNATURE`: the quote is in the response
`payment_invalid`	402	`abandon`	The payment header is malformed or not x402 version 2 (`X-PAYMENT` of version 1 included); wrong network, asset, recipient, amount or validity window; the signature check failed; a renewal or traffic paid by another wallet
`insufficient_funds`	402	`wait_and_retry`	The wallet does not have enough USDC. Top up the wallet and repeat the same request while the authorization is valid
`quote_expired`	402	`resign`	The quote is expired or already paid, and your authorization has expired too. A new quote is in the response
`payment_expired`	402	`resign`	The authorization expired unused or was cancelled. Nothing was taken. A new quote is in the response
`invalid_request`	400	`abandon`	Invalid field, unknown field, invalid JSON, body larger than 64 KiB; country, period, quantity, tier, package or options not available; a second residential package; rules of the specific endpoint
`terms_not_accepted`	400	`resign`	`accept_terms` versions are not current. The body contains `offer_version` and `privacy_version`
`purpose_not_allowed`	403	`abandon`	`intended_use` is not in the catalog list
`wallet_rejected`	403	`abandon`	The wallet is blocked or on a sanctions list
`unauthorized`	401	`abandon`	No `Authorization: Bearer x402_…` header; the wallet signature does not match the challenge
`order_not_found`	404	`abandon`	The order does not exist, or the token is not valid for it
`not_found`	404	`abandon`	The top-up or the challenge does not exist, or the token is not valid for it
`payment_replayed`	409	`abandon`	The same authorization (payer and nonce) came with different content
`payment_not_settleable`	409	`wait_and_retry`	The quote is no longer valid, but your authorization can still be executed. Wait until `authorization_expires_at` before signing a new one
`payment_under_review`	409	`human_required`	The payment is being reviewed by our staff
`quote_bound_to_other_wallet`	409	`resign`	Another wallet has already used this quote. A new quote is in the response
`quote_payment_in_progress`	409	`wait_and_retry`	Another payment for this quote is being processed
`quote_config_mismatch`	409	`abandon`	The body of the paid request does not match the quote, or a repeat of a paid authorization carries another request
`idempotency_key_conflict`	409	`abandon`	Your wallet has already used this `idempotency_key` for another payment in the last 24 hours
`rate_limited`	429	`wait_and_retry`	A limit is exceeded (Limits)
`settlement_retry`	503	`retry_same_payment`	The payment is still being processed. Repeat the same request in `retry_after_seconds`
`channel_paused`	503	`wait_and_retry`	The service is temporarily not accepting new payments
`dependency_unavailable`	503	`wait_and_retry`	A temporary failure: the price, the catalog, the payment check or another service is unavailable
`internal_error`	500	`wait_and_retry`	Unexpected error

A wrong HTTP method returns 405 with the code invalid_request.

Every response from the service has the X-Request-Id header. Give it to support when you report a problem.

Error body

Retry actions

Error codes

On this page