---
title: "x402 error codes: meanings and fixes | Settlens"
description: "Every x402 V2 error code with its meaning, the fix and the Settlens check that detects it where one exists, including the non-terminal settlement_pending."
url: https://settlens.com/learn/x402-error-codes
last_updated: 2026-10-13
published: 2026-10-13
---

# x402 error codes reference

> **In short:** The x402 V2 specification defines 16 error codes, returned in invalidReason (verify) or errorReason (settle). Signature, amount, recipient and time-window codes point at the payer's authorization; settlement_pending is the only one marked non-terminal: reconcile on chain with the returned hash before retrying.

The x402 V2 specification defines a short list of error codes that facilitators and resource servers return when a payment fails. This reference gives each code's meaning as specified, what to do about it, and the Settlens check that catches the cause in advance, where one exists.

Section 9 of the [x402 V2 core specification](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) 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`](https://settlens.com/learn/x402-v2-headers#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.

> **Checked on Oct 13, 2026**
>
> The list matches section 9 of the V2 core specification in the x402-foundation/x402 repository on that date. Codes are added as the specification evolves: `settlement_pending` is new in V2, for example.

## 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`](https://settlens.com/learn/glossary#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](https://settlens.com/learn/x402-facilitator-security) 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.

_verify-payment on the specification example with one field changed_

| Change | Fields that turn false | Matching code |
| --- | --- | --- |
| Specification example, inside its window | None: verified | None |
| Requirement payTo changed | `recipientBound` | [Recipient mismatch](https://settlens.com/learn/x402-error-codes#invalid_exact_evm_payload_recipient_mismatch) |
| Requirement amount changed to 20000 | `amountBound` | [Value mismatch](https://settlens.com/learn/x402-error-codes#invalid_exact_evm_payload_authorization_value_mismatch) |
| Checked before validAfter | `fresh` | [Not yet valid](https://settlens.com/learn/x402-error-codes#invalid_exact_evm_payload_authorization_valid_after) |
| Checked after validBefore | `fresh` | [Expired](https://settlens.com/learn/x402-error-codes#invalid_exact_evm_payload_authorization_valid_before) |
| Network changed to eip155:8453 | `signatureValid` | [Invalid signature](https://settlens.com/learn/x402-error-codes#invalid_exact_evm_payload_signature) |

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](https://settlens.com/learn/eip-3009) explains why, and [Verify](https://settlens.com/product/verify) describes the offline check.

## Codes outside section 9

- **Scheme-specific codes.** The [exact EVM scheme](https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md) 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](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md) 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](https://settlens.com/learn/x402-v1-to-v2-migration).
- **HTTP status.** The [HTTP transport](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md) 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

**What does settlement_pending mean in x402?**

The facilitator broadcast the settlement transaction but could not confirm it. The code is non-terminal: the response carries the transaction hash and network, and the caller should check that transaction on chain before deciding whether to retry.

**What is the difference between invalid_scheme and unsupported_scheme?**

The specification defines invalid_scheme as a scheme that is not supported and unsupported_scheme as a scheme the facilitator does not support. Both mean the same fix: choose a scheme the facilitator lists in GET /supported.

**Which HTTP status code comes with an x402 error?**

The HTTP transport maps categories: 400 for an invalid payment, 402 when verification or settlement fails, 500 for a server error. The specific code travels in invalidReason or errorReason.

## Sources

1. [x402 protocol specification, version 2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) — x402 Foundation
2. [x402 protocol specification, version 1](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md) — x402 Foundation
3. [x402 scheme: exact on EVM](https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md) — x402 Foundation
4. [x402 HTTP transport, version 2](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md) — x402 Foundation