Learn / Troubleshooting

x402 payment refusal codes and fixes

When a payment fails, the reason should be specific enough to fix. Our facilitator never answers with a bare "invalid". Here are the codes you will see most.

Signing problems

Timing problems

Money and terms

Not your fault

CHAIN_READ_FAILED and SVM_VERIFY_UNREACHABLE mean we could not read the chain. The authorization is untouched; retry shortly. The full machine-readable list with fault and retry flags is at /facilitator/reasons.

Common questions

Why did my x402 payment fail with SIGNATURE_MISMATCH?

The signature does not recover to the from address, usually because the EIP-712 domain (token name, version, chain ID, contract) is wrong.

Is a failed x402 payment charged?

No. A refused payment never settles, so no USDC moves.

Which refusals are safe to retry?

Timing and chain-read errors are retryable; /facilitator/reasons marks each code retryable or not.

Keep reading

x402 verify vs settleEIP-3009 transferWithAuthorization, explainedThe x402 402 response, field by fieldAll x402 guides
See what our facilitator supports
LearnDocsSettlement policyEndpoint report