x402 error reference
What each x402 error means and how to fix it, taken from the source of the official @x402 packages, version 2.31. It covers the exact scheme on EVM chains, which is what most x402 payments use.
Errors from the facilitator
These arrive in the error field of a 402 quote or the errorReason of a settlement, after the seller passed your payment to its facilitator.
| Code | Meaning |
|---|---|
invalid_exact_evm_insufficient_balance | The paying wallet holds less of the token than the quoted amount. |
invalid_exact_evm_signature | The signature does not match the transfer authorization for this token and chain. |
invalid_exact_evm_missing_eip712_domain | The seller's quote has no token name or version in extra. |
invalid_exact_evm_token_name_mismatch | The token name in the quote is not the name the token contract reports. |
invalid_exact_evm_token_version_mismatch | The token version in the quote is not the version the token contract reports. |
invalid_exact_evm_recipient_mismatch | The payment is addressed to a different wallet than the quote's payTo. |
invalid_exact_evm_authorization_value | The signed amount is not exactly the quoted amount. |
invalid_exact_evm_payload_authorization_valid_before | The payment authorization has expired, or expires within the next few seconds. |
invalid_exact_evm_payload_authorization_valid_after | The payment authorization is not valid yet. |
invalid_exact_evm_nonce_already_used | This exact payment authorization has already been spent or cancelled. |
invalid_exact_evm_eip3009_not_supported | The quoted token cannot be paid with a signed transfer authorization. |
invalid_exact_evm_transaction_simulation_failed | The facilitator simulated the transfer and it failed for a reason it could not identify. |
invalid_exact_evm_network_mismatch | The payment was made for a different network than the one quoted, or for one the facilitator does not know. |
invalid_exact_evm_scheme | The payment or the requirements name a scheme other than exact. |
invalid_exact_evm_non_canonical_signature | The signature is a valid shape but uses the high-s form, which is rejected. |
invalid_exact_evm_failed_to_verify_signature | The facilitator could not complete signature verification. |
invalid_exact_evm_transaction_failed | The payment passed verification but the on-chain transfer failed. |
Errors from the client
These are thrown by the official client before it sends any payment.
| Message | Meaning |
|---|---|
All payment requirements were rejected by spendControls.maxAmountPerPayment | The official client refused to pay because every option costs more than its per-payment cap. |
No network/scheme registered for x402 version: 2 which comply with the payment requirements | The client has no wallet scheme registered for any option the seller offers. |
Invalid payment required header | The client could not read the seller's quote. |
Look one up from a script or agent
curl 'https://x402testendpoint.com/api/errors?q=invalid_exact_evm_signature'