← All guides

x402 payment errors: causes, checks, and fixes

An x402 payment can fail at four different layers: the challenge the server issued, the wallet that tried to pay, the facilitator that verified and settled it, or the settlement itself. Each layer leaves different evidence. This guide maps the errors you will actually see to the layer that produced them, and gives the safe next step for each.

Start with the layer, not the error

1. Challenge. The server’s 402 response defines what it will accept: amount, asset, network, scheme, recipient. Most “payment” bugs are really challenge mismatches: a stale challenge, the wrong network, an amount that changed.
2. Wallet and signing. The client builds and signs the payment payload. Wrong fields, an expired allowance, or an invalid signature fail here, before any money moves.
3. Facilitator verify and settle. The facilitator checks the payload against the challenge and submits settlement. Its error codes, below, are the most precise evidence in the whole flow.
4. Settlement. The on-chain transaction itself. Settlement can succeed while delivery fails, and can still be in flight while a retry is already asking again.

Facilitator error codes

These codes come back from facilitator verification and settlement. Treat the exact response body as evidence: capture it before you change anything.

Code	What it means	Safe next step
insufficient_funds	The paying wallet does not hold enough of the asset, or of the gas token, on the required network.	Check the wallet balance on the exact network named in the challenge. Fund it, or pay a resource priced within the balance. Do not retry unchanged.
invalid_payload	The payment payload does not match what the server asked for: wrong fields, wrong encoding, or a payload built for a different challenge.	Rebuild the payload from the current challenge response, never from a cached one.
invalid_network	The payment was attempted on a network the server does not accept for this resource.	Pay on the network named in the challenge. Similar names are different networks: base and base-sepolia settle in different places.
invalid_scheme	The payment scheme, for example “exact”, is not one the server supports for this resource.	Use a scheme listed in the challenge’s accepts array.
amount_too_low	The amount offered is below the price the server requires.	Pay the amount stated in the challenge. Prices can differ per resource and change over time.
kyt_risk_detected	The facilitator’s risk screening rejected the transaction.	This is a compliance stop, not a bug. Do not retry with variations. Use a different funding source, or take it up with the facilitator.
preflight_validation_failed	The facilitator’s pre-settlement checks failed: allowances, signatures, or payload consistency.	Re-check token allowances and signature validity, rebuild the payload from a fresh challenge, and retry once.
settle_exact_failed_onchain	Verification passed, but the on-chain settlement transaction failed.	Confirm the settlement status on-chain before paying again. A second payment sent without that confirmation is how double payments happen.

An unrecognized code is still evidence. Read it as a payload problem first: rebuild from a fresh challenge, confirm the network and scheme, and only then suspect the server.

The v1 / v2 header mismatch

x402 version 1 clients send the payment in the X-PAYMENT header. Version 2 uses PAYMENT-SIGNATURE, with PAYMENT-REQUIRED and PAYMENT-RESPONSE on the other side of the exchange. A v1 client paying a v2 server, or the reverse, produces a payment the other side never reads. The retry still returns 402, the money may even settle, and it looks as if the payment vanished. Before debugging anything else, confirm which header your client sends and which header the server reads.

Paid, but still blocked

A settled payment and a delivered resource are two different events. If the retry raced the settlement, or the proof was attached to a stale challenge, the server answers 402 again. The rule that prevents almost every double payment in this flow: confirm settlement before paying twice. Payload’s engineering notes walk through a real case in detail: Paid and blocked: why your agent still gets a 402 after paying.

Diagnose it with callx402

callx402 is Payload’s diagnostics tool for exactly this work. Its six tools split the job by layer: x402_status checks the state of an endpoint or payment, x402_diagnose produces a structured diagnosis from a captured exchange, x402_evidence assembles the proof, x402_explain explains a captured error in plain language, and x402_recover and x402_resolve guide the fix. The local version is free: npx callx402.

Questions