# What do x402 error codes mean, and how do I fix a failed payment?

> 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.

| 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](https://www.ask402.ai/tools/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

- [x402 version 2 specification (error codes)](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md)
- [x402 version 2 HTTP transport specification](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md)
- [x402 FAQ](https://docs.x402.org/faq)
- [Coinbase CDP facilitator documentation](https://docs.cdp.coinbase.com/x402/seller/facilitator)

---

Facts checked against the sources above on 2026-11-20. Canonical page: https://www.ask402.ai/x402/x402-error-codes
