Client Path
Lesson 3 of 8
12 min

Handling Payment Challenges

Learning Objectives

  • Identify common payment errors
  • Implement proper error handling
  • Check wallet balance before paying
  • Handle payment failures gracefully

Common Errors

When working with x402 payments, you'll encounter three main types of errors:

InsufficientFundsError: Your wallet doesn't have enough USDC
PaymentRejectedError: The facilitator rejected the payment
TimeoutError: Settlement took too long
typescript
import { wrapFetchWithPayment, InsufficientFundsError, PaymentRejectedError, TimeoutError } from '@x402/fetch';
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Setup client
const evmSigner = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

try {
  const response = await fetchWithPayment('https://api.example.com/data');
  const data = await response.json();
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.error('Please add USDC to:', error.walletAddress);
  } else if (error instanceof PaymentRejectedError) {
    console.error('Payment rejected:', error.reason);
  } else if (error instanceof TimeoutError) {
    console.error('Payment timed out, please retry');
  } else {
    console.error('Unexpected error:', error);
  }
}

Interactive Playground

typescript
Output

Click "Run Code" to see the output