What do x402 error codes mean, and how do I fix a failed payment?
Short answer
A failed x402 payment returns status 402 again with a machine-readable code. The most common are insufficient_funds (the wallet lacks the token on that network), an expired or not-yet-valid authorization (usually a clock or timeout problem), and a signature or amount mismatch. Clients should act on the code, never on the message text.
Where the error appears
- Before payment is accepted: the server replies 402 again. In version 2 the
errorfield is inside thePAYMENT-REQUIREDheader. In version 1 it is in the JSON body. - From a facilitator's
/verify:invalidReasongives the code. - From settlement:
errorReasonin thePAYMENT-RESPONSEheader gives the code.
The specification says clients must use the code and must not rely on the wording of the message, which can change.
The codes
The meanings and fixes below are our plain-English reading of each code in the specification.
| Code | What it means | What to do |
|---|---|---|
insufficient_funds | The paying wallet does not hold enough of the token on that network | Fund the wallet with the right token on the right network. USDC on one network cannot pay an offer on another |
invalid_exact_evm_payload_authorization_valid_before | The authorization had expired by the time it was checked | Sign a fresh payment and send it straight away. Check your machine's clock |
invalid_exact_evm_payload_authorization_valid_after | The authorization is not valid yet | Almost always a clock running ahead. Sync the clock |
invalid_exact_evm_payload_authorization_value_mismatch | The signed amount is not the amount asked for | Sign exactly the amount in the offer. With exact, paying more fails too |
invalid_exact_evm_payload_recipient_mismatch | The signed recipient is not the offer's payTo address | Pay the address in the offer you chose, unchanged |
invalid_exact_evm_payload_signature | The signature does not check out | Check you signed with the paying wallet's key and used the token details from the offer's extra field (name and version) |
invalid_network | The payment names a network the server or facilitator does not accept for this offer | Use a network listed in accepts |
invalid_scheme / unsupported_scheme | The scheme is wrong for this offer, or not supported | Use a scheme listed in accepts. Not every facilitator handles every scheme |
invalid_x402_version | The version number is not one the server accepts | Match the version of the 402 reply. Update old client libraries |
invalid_payload | The payment could not be read | Usually a client bug: bad base64, missing fields, or a version 1 payload sent to a version 2 server |
invalid_payment_requirements | The seller's own requirements are malformed | A seller-side problem. Report it to the service |
invalid_transaction_state | The settlement transaction did not end in a successful state | Check the transaction on a block explorer before retrying, so you do not pay twice |
unexpected_verify_error / unexpected_settle_error | The facilitator hit an error of its own | Wait and retry. If it persists, the facilitator or network is having trouble |
settlement_pending | The transaction was sent but is not confirmed yet. Version 2 only | Not a failure. Wait for confirmation and do not pay again |
In version 1 the amount-mismatch code is spelled invalid_exact_evm_payload_authorization_value.
The three that cause most failures
1. Funds on the wrong network. A wallet with USDC on Ethereum cannot pay an offer on Base. Look at which networks the endpoint accepts in the 402 checker, then fund that network.
2. Timing. An exact payment is valid only inside a short window, set by maxTimeoutSeconds. A slow client, a queue, or a wrong system clock pushes it outside the window. Sign and send in one step.
3. Reusing a signed payment. Each authorization works once. Retrying a request with the same payment header fails. Sign a new one for each attempt.
Other reasons a payment is refused
- Screening. Some facilitators run sanctions and transaction checks and can decline a payment on those grounds.
- Rate limits. A
429is not an x402 error. Slow down and retry after the time the server gives. - A plain
400. The payment header was malformed before any x402 check ran.
Avoiding a double charge
If a request times out after you sent a payment, you may not know whether it settled. Before paying again, check the wallet's recent transfers or the transaction named in the receipt. Some services also accept an idempotency key so that a retry does not charge twice. Check the service's documentation.
Sources
- x402 version 2 specification (error codes)
- x402 version 2 HTTP transport specification
- x402 FAQ
- Coinbase CDP facilitator documentation
Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.
Related questions
Who writes this. Ask402 is published by Havok Holdings LLC, which also runs Agent402, one of the x402 services covered here. Agent402 is labelled wherever it appears. Everything else is described from each project’s own documentation, and nobody pays to be listed.