x402 error codes reference

Section 9 of the x402 V2 core specification lists 16 standard error codes "that may be returned by facilitators or resource servers". A facilitator returns them in invalidReason of a VerifyResponse or errorReason of a SettleResponse; over HTTP, a failed settlement reaches the client in the PAYMENT-RESPONSE header of a 402 response. Each code below is spelled exactly as in the specification, with its meaning, a fix and, for 10 of them, the Settlens check or verify-payment field that detects the cause before payment. For the others, the entry says why no check applies: usually the cause lies in chain state or settlement, which Settlens never touches.

Authorization errors (exact scheme on EVM)

The payer's signed EIP-3009 authorization does not match the requirement or its time window. They come from the facilitator's checks on the payload.

invalid_exact_evm_payload_authorization_valid_after

Payment authorization is not yet valid (before validAfter timestamp).

Fix: Set validAfter in the past when signing, and check the signer's clock.

Settlens: verify-payment reports fresh: false for the same condition, offline.

invalid_exact_evm_payload_authorization_valid_before

Payment authorization has expired (after validBefore timestamp).

Fix: Sign a new authorization with a later validBefore, and submit it promptly.

Settlens: verify-payment reports fresh: false for the same condition, offline.

invalid_exact_evm_payload_authorization_value_mismatch

Payment amount does not exactly match the required amount.

Fix: Sign value equal to the requirement's amount, in atomic units.

Settlens: verify-payment reports amountBound: false for the same condition, offline.

invalid_exact_evm_payload_signature

Payment authorization signature is invalid or improperly signed.

Fix: Rebuild the EIP-712 domain from extra.name, extra.version, the chain id and the asset, and sign with the from address.

Settlens: verify-payment reports signatureValid: false for the same condition, offline.

invalid_exact_evm_payload_recipient_mismatch

Recipient address does not match payment requirements.

Fix: Sign to equal to the requirement's payTo.

Settlens: verify-payment reports recipientBound: false for the same condition, offline.

Request and support errors

The payload or the requirement is malformed, or names a version, scheme or network the facilitator does not support.

invalid_network

Specified blockchain network is not supported.

Fix: Use a CAIP-2 network that the facilitator lists in GET /supported.

Settlens: facilitator.requirement_coverage (facilitator): Every scheme/network pair advertised by the resource appears in the facilitator's /supported kinds for the same x402Version. Skipped when /supported is invalid or unavailable.

invalid_payload

Payment payload is malformed or contains invalid data.

Fix: Send a PaymentPayload with x402Version, accepted and the scheme's payload, Base64 JSON encoded.

Settlens: None: passive scans never send a payload. verify-payment does refuse an exact EVM payload without authorization and signature.

invalid_payment_requirements

Payment requirements object is invalid or malformed.

Fix: Fix the server's accepts entry: CAIP-2 network, positive integer amount, asset, payTo and maxTimeoutSeconds.

Settlens: schema.payment_requirements (offline): Every accepts entry has a non-empty scheme, a CAIP-2 network, a positive integer atomic amount, a non-empty asset and payTo, and a positive maxTimeoutSeconds. On eip155 networks payTo must be a 20-byte hex address.

invalid_scheme

Specified payment scheme is not supported.

Fix: Use a scheme that the facilitator lists in GET /supported for that network.

Settlens: facilitator.requirement_coverage (facilitator): Every scheme/network pair advertised by the resource appears in the facilitator's /supported kinds for the same x402Version. Skipped when /supported is invalid or unavailable.

unsupported_scheme

Payment scheme is not supported by the facilitator.

Fix: Point the resource at a facilitator that supports the scheme, or stop advertising it.

Settlens: facilitator.requirement_coverage (facilitator): Every scheme/network pair advertised by the resource appears in the facilitator's /supported kinds for the same x402Version. Skipped when /supported is invalid or unavailable.

invalid_x402_version

Protocol version is not supported.

Fix: Send x402Version 2 end to end, or use a facilitator that lists your version in GET /supported.

Settlens: facilitator.v2_capability (facilitator): At least one supported kind has x402Version 2.

Funds and settlement errors

The problem lies with the payer's balance or the settlement transaction. insufficient_funds can come from /verify or /settle: the specification's examples show both.

insufficient_funds

Client does not have enough tokens to complete the payment.

Fix: Fund the payer's wallet with the advertised asset on the advertised network, or choose another accepts entry.

Settlens: None: balances are chain state, which Settlens never reads.

invalid_transaction_state

Blockchain transaction failed or was rejected.

Fix: Inspect the transaction on chain (nonce already used, reverted call, gas) before trying again.

Settlens: None: the transaction only exists at settlement, which Settlens never performs.

settlement_pending

The settlement transaction was broadcast but its confirmation could not be established. Non-terminal: the transaction may still confirm. The response must carry a non-empty transaction and the network.

Fix: Reconcile the returned transaction hash on chain; retry only once it has failed or been dropped.

Settlens: None: Settlens never calls /settle.

Unexpected errors

The facilitator failed for a reason outside the payment.

unexpected_verify_error

Unexpected error occurred during payment verification.

Fix: Retry later; if it persists, read the facilitator's logs. /verify must not commit payment state, so nothing should have been charged.

Settlens: None: a facilitator's internal failures are not observable from outside.

unexpected_settle_error

Unexpected error occurred during payment settlement.

Fix: Check on chain whether a transaction was broadcast before retrying.

Settlens: None: Settlens never calls /settle.

settlement_pending in detail

settlement_pending is the only code the specification marks as non-terminal. A facilitator may return it when it broadcast the settlement transaction but could not establish its confirmation, for example after a node error or a timeout while waiting for the receipt. The SettleResponse must then carry the non-empty transaction hash and the network.

• Resource servers should not treat it as a failure to retry with a new authorization: that authorization has a new nonce and can settle on top of the first one.
• Clients should reconcile the hash on chain before paying again.
• Facilitators should return it rather than a generic error whenever a transaction may still confirm. The facilitator security guide covers the other settlement risks.

Authorization errors you can reproduce offline

The five authorization codes describe properties of the signed payload, which Settlens' offline verify-payment (and the MCP tool verify_payment_signature) check without a node. The table was computed when this page was built: the specification's example payment, then one value changed at a time. Each change turns exactly one field false, the one that matches the code a facilitator would return.

Changing the network changes the EIP-712 domain, so the signature recovers a different address: that is a signature error, not a network error. The EIP-3009 guide explains why, and Verify describes the offline check.

Codes outside section 9

• Scheme-specific codes. The exact EVM scheme defines PERMIT2_ALLOWANCE_REQUIRED, returned with HTTP 412 Precondition Failed when the payer's ERC-20 allowance to the Permit2 contract does not cover the amount and no gas-sponsoring extension applies.
• V1. The V1 specification used invalid_exact_evm_payload_authorization_value ("Payment amount is insufficient for the required payment") where V2 has invalid_exact_evm_payload_authorization_value_mismatch, and had no settlement_pending. See the V1 to V2 migration guide.
• HTTP status. The HTTP transport maps categories, not codes: 400 for a malformed payment, 402 when verification or settlement fails, 500 for a server error during payment processing.

Frequently asked questions

Sources

1. x402 protocol specification, version 2x402 Foundation · github.com
2. x402 protocol specification, version 1x402 Foundation · github.com
3. x402 scheme: exact on EVMx402 Foundation · github.com
4. x402 HTTP transport, version 2x402 Foundation · github.com