Agent skill

quicknode-common-errors

Diagnose and fix QuickNode RPC errors: nonce issues, gas failures, rate limits. Use when encountering blockchain RPC errors, failed transactions, or connection issues. Trigger with phrases like "quicknode error", "RPC error", "nonce too low", "gas estimation failed".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/quicknode-pack/skills/quicknode-common-errors

SKILL.md

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

Next Steps

For debugging, see quicknode-debug-bundle.

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results