Error Handling

Decode contract reverts, handle wallet rejections, and recover from RPC errors in Sei apps

Error handling

Most transaction failures fall into three categories: contract reverts, wallet rejections, and RPC errors. This page shows how to decode each type and respond correctly.

Try it: see real errors

The RunSnippet widget shows whatever the RPC returns, including failures. These two live calls to Sei Mainnet fail on purpose. They show the exact error shape that your code has to handle.

Contract reverts

When a transaction reverts and the contract gives a revert reason, the error contains that reason.

viem

import { ContractFunctionRevertedError, BaseError } from 'viem';

try {
  await client.simulateContract({
    address: TOKEN,
    abi: ERC20_ABI,
    functionName: 'transfer',
    args: ['0xRecipient', 1_000_000n],
    account,
  });
} catch (err) {
  if (err instanceof BaseError) {
    const revert = err.walk((e) => e instanceof ContractFunctionRevertedError);
    if (revert instanceof ContractFunctionRevertedError) {
      console.error('Revert reason:', revert.data?.errorName);
      // e.g. 'ERC20InsufficientBalance'
    }
  }
}

Simulating before sending

Always simulate write calls before you submit them. Simulation runs the call against the current chain state and reports reverts before you spend gas:

viem

import { ContractFunctionRevertedError, BaseError } from 'viem';

async function safeWrite(params: Parameters<typeof walletClient.writeContract>[0]) {
  // 1. Simulate — reverts here cost no gas
  const { request } = await client.simulateContract(params);
  // 2. Execute only if simulation passes
  return walletClient.writeContract(request);
}

Wallet rejections

Users can reject signature and transaction requests. These rejections have a predictable error code:

viem

import { UserRejectedRequestError } from 'viem';

try {
  await walletClient.sendTransaction({ to: '0xRecipient', value: 1n });
} catch (err) {
  if (err instanceof UserRejectedRequestError) {
    // User cancelled — don't show an error, just reset UI state
    console.log('User rejected the request');
  }
}

Insufficient funds

viem

import { InsufficientFundsError } from 'viem';

try {
  await walletClient.sendTransaction({ to: '0xRecipient', value: parseEther('9999') });
} catch (err) {
  if (err instanceof InsufficientFundsError) {
    console.error('Not enough SEI for this transaction');
  }
}

Classifying any error

This utility handles the most common cases in one place:

import {
  BaseError,
  ContractFunctionRevertedError,
  UserRejectedRequestError,
  InsufficientFundsError,
} from 'viem';

function classifyError(err: unknown): string {
  if (err instanceof UserRejectedRequestError) return 'rejected';
  if (err instanceof InsufficientFundsError)  return 'insufficient_funds';

  if (err instanceof BaseError) {
    const revert = err.walk((e) => e instanceof ContractFunctionRevertedError);
    if (revert instanceof ContractFunctionRevertedError) {
      return `revert:${revert.data?.errorName ?? 'unknown'}`;
    }
  }

  return 'unknown';
}

RPC errors and retries

You can retry transient RPC failures, such as network timeouts and rate limits. Do not retry contract reverts or user rejections. Those failures are deterministic.

async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  let lastError: unknown;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      // Don't retry user rejections or contract reverts
      if (
        err instanceof UserRejectedRequestError ||
        err?.code === 4001 ||
        err?.code === 'CALL_EXCEPTION'
      ) {
        throw err;
      }
      lastError = err;
      if (attempt < maxAttempts) {
        await new Promise((r) => setTimeout(r, 500 * attempt)); // backoff
      }
    }
  }
  throw lastError;
}

// Usage
const balance = await withRetry(() =>
  client.readContract({ address: TOKEN, abi: ERC20_ABI, functionName: 'balanceOf', args: [owner] })
);