Free utility · callx402
x402 error code lookup
Paste the error code from your facilitator's response, or paste the whole response, and get what the code means, which layer failed, the safe next step, and whether retrying is safe. Everything runs in your browser; nothing is uploaded.
Codes checked against the facilitator reference on November 10, 2026. Meanings follow the Coinbase Developer Platform x402 troubleshooting reference, checked November 10, 2026. Layer, next step, and retry guidance are Payload's.
When the code is not the whole story
A single failed payment is a lookup. A captured exchange, with headers, requirements, and the settlement state checked, is a diagnosis.
Free: callx402 on your machine
Six MCP tools that classify a captured x402 exchange layer by layer and say what to do next. Runs locally; nothing leaves your machine.
npx callx402
Hosted: diagnosis inside the incident
The same classification as a hosted action: explain an error for $0.50 by card or $0.025 in USDC, or a full diagnosis for $2 by card or $0.10 in USDC.
The full code reference
Every code the CDP Facilitator returns in practice, with the layer that produced it and the safe next step. The x402 troubleshooting guide explains the four-layer model behind the classifications.
| 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. |
Code families covered as patterns
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
Where do I find my error code?
In the facilitator's JSON response: invalidReason when verification fails, errorReason when settlement fails. Paste the whole response into the lookup above and it will find the code in it.
Is it safe to retry a failed x402 payment?
It depends on the code, which is what the retry verdict in each result is for. Authorization and requirements failures are safe to retry after the named fix. Settlement failures are different: the payment may already have landed, so confirm the transaction onchain before paying again.
Why does my code start with invalid_exact_evm_permit2?
Your token settles through Permit2 instead of EIP-3009. Permit2 has a parallel code family, and one member matters most: invalid_exact_evm_permit2_payload_allowance_required means the one-time Permit2 approval has not been granted yet, so submit that approval transaction first.
What if my code is not listed?
Some families are covered as patterns rather than individual codes: Solana exact transaction variants, batch-settlement codes, and Solana upto codes. If your code matches none of the patterns, capture the full exchange and treat it like unknown_error: report it with the network, scheme, and error field included.