alchemy-common-errors | alchemy-pack

Stats

Actions

Tags

alchemy-common-errors | alchemy-pack

Alchemy Common Errors

Overview

Troubleshooting guide for Alchemy SDK errors covering rate limits, RPC failures, invalid parameters, and network-specific issues.

Error Reference

Authentication & Rate Limits

HTTP Code	Error	Root Cause	Fix
`401`	Unauthorized	Invalid or missing API key	Verify key in Alchemy Dashboard
`403`	Forbidden	API key disabled or app deleted	Create new app in Dashboard
`429`	Too Many Requests	Rate limit exceeded	Implement backoff; upgrade plan
`429`	Compute Units exceeded	CU quota depleted	Check CU usage in Dashboard

Alchemy Rate Limits by Plan

Plan	Compute Units/sec	Throughput
Free	330 CU/s	~25 requests/s
Growth	660 CU/s	~50 requests/s
Scale	Custom	Custom

RPC & Query Errors

// Common RPC error handler
import { Alchemy, Network } from 'alchemy-sdk';

async function safeAlchemyCall<T>(
  operation: () => Promise<T>,
  context: string
): Promise<T | null> {
  try {
    return await operation();
  } catch (error: any) {
    const code = error.code || error.response?.status;

    switch (code) {
      case -32602: // Invalid params
        console.error(`[${context}] Invalid parameters: ${error.message}`);
        console.error('Common causes: wrong address format, invalid block number, missing 0x prefix');
        break;

      case -32600: // Invalid request
        console.error(`[${context}] Malformed JSON-RPC request`);
        break;

      case -32601: // Method not found
        console.error(`[${context}] RPC method not available on this network`);
        console.error('Some Enhanced APIs are Ethereum-only');
        break;

      case -32000: // Server error
        console.error(`[${context}] Node server error — usually transient, retry`);
        break;

      case 429:
        const retryAfter = error.response?.headers?.['retry-after'] || 1;
        console.error(`[${context}] Rate limited — retry after ${retryAfter}s`);
        break;

      default:
        console.error(`[${context}] Unknown error: ${code} — ${error.message}`);
    }
    return null;
  }
}

NFT API Errors

Error	Root Cause	Fix
Empty `ownedNfts`	Address has no NFTs on this chain	Check correct network
Missing `image.cachedUrl`	IPFS/Arweave gateway timeout	Use `image.originalUrl` fallback
`getNftsForContract` empty	Contract not indexed	Wait for indexing; try `refreshContract`
Spam NFTs in results	No spam filter	Add `excludeFilters: ['SPAM']` option
`getNftMetadataBatch` fails	Batch too large	Limit to 100 tokens per batch

Enhanced API Errors

Error	Root Cause	Fix
`getAssetTransfers` empty	Wrong category	Include all: EXTERNAL, ERC20, ERC721, ERC1155
`getTokenBalances` timeout	Too many tokens	Paginate or use specific contract addresses
`getTokenMetadata` null fields	Token not verified	Handle null `name`/`symbol` gracefully
WebSocket disconnect	Idle timeout (5 min)	Implement auto-reconnect logic

Network-Specific Issues

// Diagnostic function
async function diagnoseAlchemyIssue(alchemy: Alchemy): Promise<string[]> {
  const issues: string[] = [];

  try {
    const blockNumber = await alchemy.core.getBlockNumber();
    console.log(`Connected: block #${blockNumber}`);
  } catch (err: any) {
    if (err.message?.includes('apiKey')) issues.push('API key invalid or missing');
    else if (err.code === 'ECONNREFUSED') issues.push('Cannot reach Alchemy servers — check network');
    else issues.push(`Connection error: ${err.message}`);
  }

  return issues;
}

Quick Diagnostic

# Test Alchemy API directly
curl -s "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":0}' | jq .

# Check CU usage (requires auth token)
curl -s "https://dashboard.alchemy.com/api/stats" \
  -H "Authorization: Bearer ${ALCHEMY_AUTH_TOKEN}" | jq .

Output

Error classified by type (auth, rate limit, RPC, network)
Root cause identified with specific fix
Diagnostic function for automated troubleshooting

Resources

Next Steps

For collecting debug bundles, see alchemy-debug-bundle.