Error Codes

Reference for JSON-RPC and nodewell-specific error codes.

JSON-RPC Standard Errors

Code	Message	Description
-32700	Parse error	Invalid JSON
-32600	Invalid Request	Request object invalid
-32601	Method not found	Method does not exist
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Internal JSON-RPC error

Ethereum Errors

Code	Message	Description
-32000	Server error	Generic server error
-32001	Resource not found	Block/tx not found
-32002	Resource unavailable	Requested data unavailable
-32003	Transaction rejected	Transaction rejected
-32004	Method not supported	Method not supported on this network

nodewell Specific Errors

Code	Message	Description
-32005	Rate limit exceeded	Too many requests
-32006	Invalid API key	API key invalid or missing
-32007	API key expired	API key has expired
-32008	Insufficient quota	Daily quota exceeded

Error Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Missing required parameter: address"
  }
}

Common Issues & Solutions

Invalid API Key

{
  "error": {
    "code": -32006,
    "message": "Invalid API key"
  }
}

Solution: Check your API key is correct and included in the URL.

Rate Limit Exceeded

{
  "error": {
    "code": -32005,
    "message": "Rate limit exceeded. Please retry after 1 second."
  }
}

Solution: Implement retry logic with exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === -32005 && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
}

Block Not Found

{
  "error": {
    "code": -32001,
    "message": "Block not found"
  }
}

Solution: Verify the block number/hash exists. For recent blocks, wait for confirmation.

Execution Reverted

{
  "error": {
    "code": 3,
    "message": "execution reverted",
    "data": "0x..."
  }
}

Solution: The contract call reverted. Decode the error data using your library of choice to read the revert reason.

Gas Estimation Failed

{
  "error": {
    "code": -32000,
    "message": "gas required exceeds allowance"
  }
}

Solution: The transaction would fail. Check:

• Sufficient balance for gas
• Contract logic doesn't revert
• Correct parameters

Error Handling Examples

JavaScript

try {
  const result = await provider.call(tx);
} catch (error) {
  switch (error.code) {
    case -32005:
      console.log('Rate limited, retrying...');
      break;
    case -32602:
      console.log('Invalid parameters:', error.message);
      break;
    default:
      console.error('RPC error:', error);
  }
}

ethers.js

import { isError } from 'ethers';

try {
  await contract.someMethod();
} catch (error) {
  if (isError(error, 'CALL_EXCEPTION')) {
    console.log('Contract reverted:', error.reason);
  } else if (isError(error, 'NETWORK_ERROR')) {
    console.log('Network issue');
  }
}