Ask402

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 error field is inside the PAYMENT-REQUIRED header. In version 1 it is in the JSON body.
  • From a facilitator's /verify: invalidReason gives the code.
  • From settlement: errorReason in the PAYMENT-RESPONSE header 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.

CodeWhat it meansWhat to do
insufficient_fundsThe paying wallet does not hold enough of the token on that networkFund 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_beforeThe authorization had expired by the time it was checkedSign a fresh payment and send it straight away. Check your machine's clock
invalid_exact_evm_payload_authorization_valid_afterThe authorization is not valid yetAlmost always a clock running ahead. Sync the clock
invalid_exact_evm_payload_authorization_value_mismatchThe signed amount is not the amount asked forSign exactly the amount in the offer. With exact, paying more fails too
invalid_exact_evm_payload_recipient_mismatchThe signed recipient is not the offer's payTo addressPay the address in the offer you chose, unchanged
invalid_exact_evm_payload_signatureThe signature does not check outCheck you signed with the paying wallet's key and used the token details from the offer's extra field (name and version)
invalid_networkThe payment names a network the server or facilitator does not accept for this offerUse a network listed in accepts
invalid_scheme / unsupported_schemeThe scheme is wrong for this offer, or not supportedUse a scheme listed in accepts. Not every facilitator handles every scheme
invalid_x402_versionThe version number is not one the server acceptsMatch the version of the 402 reply. Update old client libraries
invalid_payloadThe payment could not be readUsually a client bug: bad base64, missing fields, or a version 1 payload sent to a version 2 server
invalid_payment_requirementsThe seller's own requirements are malformedA seller-side problem. Report it to the service
invalid_transaction_stateThe settlement transaction did not end in a successful stateCheck the transaction on a block explorer before retrying, so you do not pay twice
unexpected_verify_error / unexpected_settle_errorThe facilitator hit an error of its ownWait and retry. If it persists, the facilitator or network is having trouble
settlement_pendingThe transaction was sent but is not confirmed yet. Version 2 onlyNot 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 429 is 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

Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.

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.