Skip to main content
This page covers common errors when integrating with x402. For general questions, see the FAQ.
Need help? Join the x402 Discord for support from the community.

​
Common Errors

​
Unable to estimate gas

This is a client-side EVM error, not an x402 error. It occurs when your wallet or provider can’t simulate the transaction.
This error happens when creating the payment payload, before the facilitator is called.
  • Insufficient token balance: Your wallet doesn’t have enough USDC to cover the payment amount.
  • Invalid recipient address: The payTo address in payment requirements is invalid or a contract that can’t receive tokens.
  • Network RPC issues: The RPC endpoint is unavailable or rate-limited.
  • Wrong network: Your wallet is connected to a different network than specified in the payment requirements.
Verify your wallet has sufficient balance and is connected to the correct network:
// 1. Check your wallet balance
const balance = await provider.getBalance(walletAddress);
console.log("ETH Balance:", balance);

// 2. Check USDC balance
const usdcContract = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, provider);
const usdcBalance = await usdcContract.balanceOf(walletAddress);
console.log("USDC Balance:", usdcBalance);

// 3. Verify payment requirements
const response = await fetch(url);
if (response.status === 402) {
  const paymentRequired = response.headers.get("PAYMENT-REQUIRED");
  console.log("Payment requirements:", JSON.parse(atob(paymentRequired)));
}

​
invalid_payload or invalid_request: doesn't match schema (oneOf)

These errors mean the payment payload is malformed or doesn’t match what the facilitator expects. Common variants:
The payload structure doesn’t match the x402Version. v1 and v2 have different payload schemas.How to fix: Ensure your payload structure matches the version you’re using. If using v2, set x402Version: 2 and use the v2 payload shape. See the Migration Guide for schema differences.
Your code mixes imports from v1 and v2 packages, causing inconsistent payload formats.How to fix: Use only v2 packages (@x402/*) or only v1 packages. Avoid mixing x402-express with @x402/express in the same process.
Required fields are missing, malformed, or don’t match the payment requirements (e.g., wrong payTo, network, or amount).How to fix: Compare your payload to the PAYMENT-REQUIRED header. Ensure scheme, network, payTo, and amount match. For price format, use a dollar-prefixed string (e.g. "$0.10").
The signature doesn’t verify against the authorization data.How to fix: Ensure you’re signing with the correct private key and that the payload hasn’t been modified. Check network ID (CAIP-2 format) and expiry (validBefore).

​
402 Payment Required (after attaching payment header)

The server is still returning 402 even though you included the PAYMENT-SIGNATURE header.
  • Wrong header name: Using legacy X-PAYMENT instead of PAYMENT-SIGNATURE.
  • Invalid signature: Wrong chain ID or payload fields.
  • Insufficient amount: Payment amount is less than required.
  • KYT flagged: Payer address was flagged by Know Your Transaction checks.
Check the error field in the server’s JSON response for details. Common fixes:
  • Use PAYMENT-SIGNATURE header (not X-PAYMENT)
  • Verify your USDC balance meets the required amount
  • Check that your network ID matches (e.g., eip155:8453 for Base mainnet)

​
Works on testnet, fails on mainnet

Your integration works on Base Sepolia but fails on Base mainnet.
  • Wrong network ID: Using testnet ID (eip155:84532) instead of mainnet (eip155:8453).
  • Wrong facilitator: The x402.org testnet facilitator (https://x402.org/facilitator) does NOT support mainnet.
  • No mainnet USDC: Your wallet has testnet USDC but not mainnet USDC.
  • Insufficient gas: Mainnet requires real ETH for gas fees.
  • Update network to eip155:8453 (Base mainnet)
  • Use CDP facilitator for mainnet: https://api.cdp.coinbase.com/platform/v2/x402
  • Fund your wallet with mainnet USDC and ETH
  • See Network Support for facilitator details

​
No scheme registered

The x402 client or server doesn’t have a payment scheme registered for the requested network.
  • Missing scheme registration: You didn’t call .register() for the network.
  • Wrong network ID format: Using legacy format (base-sepolia) instead of CAIP-2 (eip155:84532).
Register the appropriate scheme for your network:
// Client-side
import { registerExactEvmScheme } from "@x402/evm/exact/client";
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Server-side
import { ExactEvmScheme } from "@x402/evm/exact/server";
const server = new x402ResourceServer(facilitatorClient)
  .register("eip155:8453", new ExactEvmScheme());
See Migration Guide for CAIP-2 network ID format.

​
Facilitator API Error Codes

When the facilitator returns an error, check the invalidReason (for verify) or errorReason (for settle) field.
Error CodeMeaning
insufficient_fundsPayer doesn’t have enough tokens
invalid_schemeUnsupported payment scheme
invalid_networkUnsupported network
invalid_x402_versionWrong protocol version (v1 vs v2 mismatch)
invalid_payloadMalformed payment payload
invalid_exact_evm_payload_signatureEVM signature verification failed
invalid_exact_evm_payload_authorization_value_too_lowPayment amount less than required
invalid_exact_evm_payload_authorization_valid_beforePayment authorization expired
invalid_exact_evm_payload_authorization_from_address_kytPayer address flagged by KYT
invalid_exact_svm_payload_transaction_simulation_failedSolana transaction simulation failed
Error CodeMeaning
settle_exact_failed_onchainTransaction failed onchain
settle_exact_node_failureBlockchain node connection failed
settle_exact_evm_transaction_confirmation_timed_outEVM transaction confirmation timed out
settle_exact_svm_transaction_confirmation_timed_outSolana transaction confirmation timed out
For the complete list, see the x402 Facilitator API Reference.

​
Still Need Help?