quicknode-common-errors

# QuickNode Common Errors

## Overview
Quick reference for the top blockchain RPC errors when using QuickNode endpoints with ethers.js or viem.

## Prerequisites
- QuickNode endpoint configured
- ethers.js or viem installed

## Instructions

### Error 1: Nonce Too Low
```
Error: nonce has already been used (error={"code":-32000,"message":"nonce too low"})
```
**Fix:**
```typescript
// Get the correct nonce before sending
const nonce = await provider.getTransactionCount(wallet.address, 'pending');
const tx = await wallet.sendTransaction({ ...txData, nonce });
```

### Error 2: Insufficient Funds
```
Error: insufficient funds for intrinsic transaction cost
```
**Fix:**
```typescript
const balance = await provider.getBalance(wallet.address);
const gasEstimate = await provider.estimateGas(txData);
const feeData = await provider.getFeeData();
const totalCost = gasEstimate * feeData.gasPrice! + txData.value;
if (balance < totalCost) {
  console.error(`Need ${ethers.formatEther(totalCost)} ETH, have ${ethers.formatEther(balance)}`);
}
```

### Error 3: Gas Estimation Failed (Call Revert)
```
Error: execution reverted (reason="ERC20: transfer amount exceeds balance")
```
**Fix:** The contract function would revert. Check contract requirements:
```typescript
try {
  const gas = await contract.transfer.estimateGas(to, amount);
} catch (err) {
  console.error('Revert reason:', err.reason);
  // Check: sufficient token balance, approvals, contract state
}
```

### Error 4: Rate Limited (429)
```
Error: 429 Too Many Requests
```
**Fix:** Implement exponential backoff or upgrade plan:
```typescript
async function retryRpc<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
  for (let i = 0; i < retries; i++) {
    try { return await fn(); }
    catch (err: any) {
      if (err.code === 'SERVER_ERROR' && i < retries - 1) {
        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries');
}
```

### Error 5: Method Not Found
```
Error: Method not found — qn_getTokenMetadataByContractAddress
```
**Fix:** This method requires an add-on. Enable it in QuickNode Dashboard > Endpoints > Add-ons.

### Error 6: WebSocket Connection Dropped
```
Error: WebSocket connection closed unexpectedly
```
**Fix:**
```typescript
const wsProvider = new ethers.WebSocketProvider(process.env.QUICKNODE_WSS);
wsProvider.websocket.on('close', () => {
  console.log('WebSocket closed, reconnecting...');
  // Reconnect logic
});
```

## Output
- Error identified from RPC response
- Targeted fix applied
- Transaction successfully sent or contract call succeeded

## Error Handling
| RPC Code | Meaning | Retryable |
|----------|---------|-----------|
| -32000 | Nonce/gas issue | Fix and retry |
| -32602 | Invalid params | No — fix request |
| -32603 | Internal error | Yes — retry |
| 429 | Rate limited | Yes — backoff |

## Resources
- [QuickNode Ethereum API](https://www.quicknode.com/docs/ethereum)
- [ethers.js Error Handling](https://docs.ethers.org/)

## Next Steps
For debugging, see `quicknode-debug-bundle`.