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
- 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.
- 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.
- 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.
- 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 paid and blocked guide walks through the four failure modes and the checklist to work before paying again.
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.
The full facilitator code reference
The eight codes above are the generic ones. The facilitator also returns scheme-specific codes, and developers paste those long strings into search exactly as they appear. Here is the complete set the CDP Facilitator returns in practice, each with its layer and safe next step. Meanings follow the Coinbase Developer Platform x402 troubleshooting reference, checked November 10, 2026. Layer, next step, and retry guidance are Payload's. The error code lookup searches the same table and can find a code inside a pasted response body.
| Code | Layer | What it means | Safe next step |
|---|---|---|---|
| Any payment | |||
insufficient_funds | Facilitator verification | The payer's balance is below the amount required. | Fund the payer with the token the route asks for, on the network the route accepts, then sign a fresh payment. Safe to retry after the fix. |
invalid_payload | Facilitator verification | The payload is malformed, fails validation, or reuses a spent authorization. It is the catch-all: a reused authorization nonce, a failed onchain simulation, and a recipient that does not match the route all arrive as this code. | Capture the full request and response. Check for a reused nonce first, then the recipient against the route, then simulate the transfer. Safe to retry after the fix. |
invalid_scheme | Payment requirements | The payload's scheme is not one the route accepts. | Read the route's accepts list and pay with one of the schemes it names (for example exact instead of upto). Safe to retry after the fix. |
invalid_network | Payment requirements | The network in the payload is not one the route accepts. | Align the CAIP-2 network identifier on both sides (eip155:8453 is Base mainnet; eip155:84532 is Base Sepolia). Testnet and mainnet identifiers are not interchangeable. Safe to retry after the fix. |
invalid_amount | Client and authorization | The amount could not be parsed, or is not a positive value. | Send the amount exactly as the payment requirements state it, in atomic units where the scheme requires them, as a positive value. Safe to retry after the fix. |
amount_too_low | Facilitator policy | The payment is below the minimum amount the facilitator will settle. | Raise the payment to at least the amount the route requires. Splitting one payment into smaller ones will keep failing. Safe to retry after the fix. |
self_send_not_allowed | Client and authorization | The payer and the recipient are the same address. | Use distinct payer and recipient addresses. A route cannot pay itself through the facilitator. Safe to retry after the fix. |
kyt_risk_detected | Facilitator policy | The payer or the recipient was declined by compliance screening (HTTP 403). | Do not retry. Identify which side was screened out and resolve it through the facilitator's compliance process; a different counterparty address may be required. Do not retry. |
request_blocked_by_location | Facilitator policy | The request came from a jurisdiction the facilitator does not serve (HTTP 403). | Route the payment through a facilitator and jurisdiction that can serve the request. Retrying from the same location changes nothing. Do not retry. |
permit2_disabled | Payment requirements | The payment needs Permit2, which is not enabled for that token or network. | Use a token and network where Permit2 is enabled, or a payment path that does not need it (for example an EIP-3009 token). Safe to retry after the fix. |
preflight_validation_failed | Facilitator verification | A check that runs before the scheme sees the payment failed. | Validate the request shape against the facilitator's requirements first: protocol version fields, headers, and payload structure. The failure is in the envelope, not the payment itself. Safe to retry after the fix. |
invalid_bazaar_extension | Payment requirements | The Bazaar discovery metadata on the 402 response is malformed. | Fix the seller's discovery metadata on the 402 response. This is a listing problem; the payment mechanics may be fine. Safe to retry after the fix. |
unsupported_payload_type | Payment requirements | The payload type is not one the facilitator handles. | Check the protocol version on both sides. The common cause is the v1 X-PAYMENT header sent to a v2 endpoint that expects PAYMENT-SIGNATURE, or the reverse. Safe to retry after the fix. |
unknown_error | Facilitator verification | The failure could not be classified (HTTP 500). The facilitator asks for these to be reported. | Capture the full exchange (network, scheme, the error field, any transaction reference) and report it. One retry with a fresh authorization is reasonable; a repeat is a report, not a loop. Safe to retry after the fix. |
| EVM exact | |||
invalid_exact_evm_payload_signature | Client and authorization | The signature does not recover to the payer address. | Re-sign with the payer's key and check the signing domain: chain ID, verifying contract, and the exact typed-data fields. Safe to retry after the fix. |
invalid_exact_evm_payload_authorization_value | Client and authorization | The amount does not exactly match the amount required. | Copy the amount from the payment requirements exactly, in atomic units. Exact-scheme payments do not round. Safe to retry after the fix. |
invalid_exact_evm_payload_authorization_valid_before | Client and authorization | The authorization expired before settlement. | Give the authorization a longer validity window, and check for clock skew and slow settlement between signing and submission. Safe to retry after the fix. |
invalid_exact_evm_payload_authorization_valid_after | Client and authorization | The authorization is not valid yet. | Check the signing clock, then wait until the valid-after time passes before submitting. Safe to retry after the fix. |
invalid_exact_evm_payload_undeployed_smart_wallet | Client and authorization | The payer is a counterfactual smart wallet with no deployment data. | Deploy the wallet first, or include the deployment data the facilitator needs to verify the signature. Safe to retry after the fix. |
smart_wallet_deployment_failed | Settlement | Deploying the payer's smart wallet during settlement failed. | Check the wallet factory and deployment funding, and confirm whether any part of the payment landed before trying again. Confirm onchain first. |
| Permit2 | |||
invalid_exact_evm_permit2_payload_signature | Client and authorization | The Permit2 signature does not verify for the payer. | Re-sign the Permit2 permitted-witness data with the payer's key, checking the domain and witness fields. Safe to retry after the fix. |
invalid_exact_evm_permit2_payload_amount | Client and authorization | The permitted amount does not match the amount required. | Set the permitted amount exactly to the amount in the payment requirements. Safe to retry after the fix. |
invalid_exact_evm_permit2_payload_deadline | Client and authorization | The Permit2 deadline has passed. | Sign again with a deadline far enough in the future to cover settlement time. Safe to retry after the fix. |
invalid_exact_evm_permit2_payload_recipient | Client and authorization | The recipient in the Permit2 data does not match the route's recipient. | Set the witness recipient to the payTo address in the payment requirements. Safe to retry after the fix. |
invalid_exact_evm_permit2_payload_spender | Client and authorization | The spender in the Permit2 data is not the contract the facilitator expects. | Use the spender named in the payment requirements (the x402 Permit2 proxy), not the token or the facilitator address. Safe to retry after the fix. |
invalid_exact_evm_permit2_payload_valid_after | Client and authorization | The Permit2 authorization is not valid yet. | Check the signing clock, then wait until the valid-after time passes. Safe to retry after the fix. |
invalid_exact_evm_permit2_payload_allowance_required | Client and authorization | The one-time Permit2 approval has not been granted yet. This is the Permit2 code to know: the payment cannot proceed until the allowance exists. | Submit the Permit2 allowance approval transaction from the payer first and let it confirm, then sign the payment. Safe to retry after the fix. |
| Solana exact | |||
invalid_exact_svm_payload_transaction_simulation_failed | Client and authorization | The Solana payment transaction failed simulation. | Rebuild the transaction and simulate it locally; the failing instruction or account is named in the simulation logs. Safe to retry after the fix. |
invalid_exact_svm_payload_transaction_sender_ata_not_found | Client and authorization | The payer has no associated token account for the asset being paid. | Create and fund the payer's associated token account for that mint, then rebuild the payment transaction. Safe to retry after the fix. |
invalid_exact_svm_payload_transaction_amount_mismatch | Client and authorization | The transaction amount does not match the amount required. | Set the transfer amount exactly to the requirement, in the token's smallest units. Safe to retry after the fix. |
| Settlement | |||
settle_exact_failed_onchain | Settlement | The settlement transaction was submitted and reverted. | Read the transaction receipt to find the revert reason; the payment did not land. Fix the cause before paying again, and keep the receipt as evidence of what happened. Confirm onchain first. |
settle_exact_node_failure | Settlement | The facilitator could not reach the network to submit or confirm. | Check whether a settlement transaction exists before doing anything else; a submission may already be in flight. Then wait for the network or facilitator to recover. Confirm onchain first. |
settle_exact_svm_transaction_confirmation_timed_out | Settlement | The Solana transaction was submitted but did not confirm in time. | Look the signature up on a Solana explorer. It may still confirm; do not pay again until its status is final. Confirm onchain first. |
settle_exact_svm_block_height_exceeded | Settlement | The Solana transaction expired before confirmation, so it cannot land. | Rebuild the payment with a fresh blockhash and submit again. The expired transaction is dead, so a fresh one cannot double-pay. Safe to retry after the fix. |
invalid_exact_evm_verification_failed | Settlement | Verification, rerun at settlement time, no longer passes: something changed between the verify call and settlement, such as an expired or consumed authorization. | Confirm no payment landed, then start a fresh payment with a new authorization rather than resubmitting the old one. Confirm onchain first. |
invalid_exact_svm_payload_transaction_ — About twenty variants share this prefix; the suffix names the specific instruction or account at fault. Treat the suffix as the diagnosis: rebuild the transaction correcting the named element, and simulate locally before resubmitting.
invalid_batch_settlement_evm_ — The batch-settlement scheme defines its own family under this prefix. The suffix names the failing element of the batch; the verify-then-settle checks in this table apply the same way.
invalid_upto_svm_ / settle_upto_svm_ — The upto scheme on Solana defines invalid_upto_svm_ codes for payment requirements, payload, channel, and settlement failures, plus settle_upto_svm_ codes for onchain and confirmation failures. Settlement-prefixed codes follow the same rule as the other settle_ codes: confirm the transaction before paying again.
Questions
My payment went through but the API still returns 402. Why?
Settlement and delivery are two different events. If the retry raced the settlement, or the payment proof was attached to a stale challenge, the server answers 402 again even though the money moved. Confirm the settlement on-chain or with the facilitator before paying a second time, and check for a v1/v2 payment header mismatch.
Is it safe to retry a failed x402 payment?
Retrying the request is always safe. Sending a second payment is not, until the first payment’s settlement status is known. Most double payments in x402 flows come from paying again while the first settlement was still in flight.
What is the difference between the X-PAYMENT and PAYMENT-SIGNATURE headers?
X-PAYMENT is the x402 v1 header; PAYMENT-SIGNATURE is the v2 header. A v1 client paying a v2 server (or the reverse) produces a payment the other side never reads, so the retry still returns 402 and it looks as if the payment vanished.
Which x402 error codes come from the facilitator?
Codes such as invalid_payload, preflight_validation_failed, settle_exact_failed_onchain, and kyt_risk_detected are issued during facilitator verification and settlement. Challenge-layer problems usually appear as a fresh 402 with a new payment challenge instead of an error code.