> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> JSON-RPC error codes, response structure, and retry strategies

Provider requests throw errors following the [JSON-RPC 2.0](https://www.jsonrpc.org/specification#error_object) and [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474) specifications.

## Error Structure

```typescript theme={null}
interface JsonRpcErrorType {
  code: number;
  message: string;
  data?: unknown;
}
```

## Standard JSON-RPC 2.0 Error Codes

Defined by [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#error_object):

| Code     | Constant           | Description                               |
| -------- | ------------------ | ----------------------------------------- |
| `-32700` | `PARSE_ERROR`      | Invalid JSON received by server           |
| `-32600` | `INVALID_REQUEST`  | JSON is not a valid request object        |
| `-32601` | `METHOD_NOT_FOUND` | Method does not exist or is not available |
| `-32602` | `INVALID_PARAMS`   | Invalid method parameter(s)               |
| `-32603` | `INTERNAL_ERROR`   | Internal JSON-RPC error                   |

## Ethereum-Specific Error Codes (EIP-1474)

Defined by [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474) in the `-32000` to `-32099` range:

| Code     | Constant                         | Description                                                     |
| -------- | -------------------------------- | --------------------------------------------------------------- |
| `-32000` | `INVALID_INPUT`                  | Missing or invalid parameters (commonly "execution reverted")   |
| `-32001` | `RESOURCE_NOT_FOUND`             | Requested resource not found (block, transaction, etc.)         |
| `-32002` | `RESOURCE_UNAVAILABLE`           | Requested resource not available (node syncing, data not ready) |
| `-32003` | `TRANSACTION_REJECTED`           | Transaction creation failed                                     |
| `-32004` | `METHOD_NOT_SUPPORTED`           | Method exists but is not implemented                            |
| `-32005` | `LIMIT_EXCEEDED`                 | Request exceeds defined limit                                   |
| `-32006` | `JSON_RPC_VERSION_NOT_SUPPORTED` | JSON-RPC protocol version not supported                         |

## Using Error Codes

```typescript theme={null}
import {
  JsonRpcError,
  INVALID_INPUT,
  RESOURCE_NOT_FOUND,
  TRANSACTION_REJECTED,
} from '@tevm/voltaire/JsonRpcError';

// Create error with code and message
const error = JsonRpcError.from(INVALID_INPUT, 'execution reverted');

// Create error with additional data (e.g., revert reason)
const revertError = JsonRpcError.from(
  INVALID_INPUT,
  'execution reverted',
  '0x08c379a0...' // ABI-encoded revert reason
);

// Check error code
if (response.error?.code === INVALID_INPUT) {
  console.log('Contract execution failed');
}
```

## Execution Reverted Errors

The `-32000` (`INVALID_INPUT`) error code is most commonly used for contract execution failures:

````typescript theme={null}
import * as Rpc from '@tevm/voltaire/jsonrpc';
import { INVALID_INPUT } from '@tevm/voltaire/JsonRpcError';

try {
  const result = await provider.request(
    Rpc.Eth.CallRequest({
      to: contractAddress,
      data: encodedCall
    })
  );
} catch (error) {
  if (error.code === INVALID_INPUT) {
    // Contract reverted - data may contain revert reason
    console.error('Execution reverted:', error.data);
  }
}

## Error Handling Patterns

### Checking for Specific Errors

```typescript
import * as Rpc from '@tevm/voltaire/jsonrpc';
import {
  INVALID_INPUT,
  METHOD_NOT_FOUND,
  RESOURCE_NOT_FOUND,
} from '@tevm/voltaire/JsonRpcError';

try {
  const block = await provider.request(
    Rpc.Eth.GetBlockByHashRequest(blockHash, false)
  );
} catch (error) {
  switch (error.code) {
    case INVALID_INPUT:
      console.error('Invalid block hash format');
      break;
    case RESOURCE_NOT_FOUND:
      console.error('Block not found');
      break;
    case METHOD_NOT_FOUND:
      console.error('Method not supported by this provider');
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}
````

## Retry Strategies

### Smart Retry with Error Code Filtering

Only retry on transient errors (not permanent failures):

```typescript theme={null}
import {
  METHOD_NOT_FOUND,
  INVALID_PARAMS,
} from '@tevm/voltaire/JsonRpcError';

async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> {
  const NON_RETRYABLE_ERRORS = new Set([
    METHOD_NOT_FOUND,    // Method will never exist
    INVALID_PARAMS,      // Parameters are wrong
  ]);

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      // Don't retry if error is non-retryable or last attempt
      if (NON_RETRYABLE_ERRORS.has(error.code) || i === maxRetries - 1) {
        throw error;
      }

      // Exponential backoff: 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
    }
  }

  throw new Error('Max retries exceeded');
}
```

### Rate Limit Handling

```typescript theme={null}
import { LIMIT_EXCEEDED } from '@tevm/voltaire/JsonRpcError';

async function callWithRateLimit<T>(
  fn: () => Promise<T>
): Promise<T> {
  while (true) {
    try {
      return await fn();
    } catch (error) {
      // If rate limited, wait and retry
      if (error.code === LIMIT_EXCEEDED) {
        await new Promise(resolve => setTimeout(resolve, 1000));
        continue;
      }
      throw error;
    }
  }
}
```

## Complete Error Reference

See `@tevm/voltaire/JsonRpcError` for:

* All error code constants
* `JsonRpcError.from()` constructor
* `ERROR_MESSAGES` lookup table

## Related

* [Method API](/jsonrpc-provider/method-api) - Method calls and responses
* [Performance](/jsonrpc-provider/performance) - Optimization strategies