Skip to main content

Troubleshooting

Solutions to common issues when using the Web3 Identity API.

Quick Diagnostics​

# Check API status
curl https://api.web3identity.com/api/health

# Check your rate limit status
curl https://api.web3identity.com/api/usage

# Test a simple endpoint
curl https://api.web3identity.com/api/ens/resolve/vitalik.eth

Common Errors​

402 Payment Required​

Symptom: API returns 402 after some requests work.

Cause: You've exceeded the free tier (100 calls/day).

Solutions:

  1. Wait for reset — Free tier resets daily at midnight UTC
  2. Authenticate with SIWE — Doubles limit to 200/day
  3. Make a payment — Use x402 to pay per request
// Check your remaining calls
const usage = await fetch('https://api.web3identity.com/api/usage');
const { remaining, resetsAt } = await usage.json();
console.log(`${remaining} calls left, resets at ${resetsAt}`);

429 Too Many Requests​

Symptom: API returns 429 with Retry-After header.

Cause: Too many requests per minute (rate limited).

Solutions:

  1. Respect rate limits — 30/min anonymous, 30/min for all tiers
  2. Add delays — Space out requests
  3. Use batch endpoints — /api/price/batch instead of individual calls
// Implement exponential backoff
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url);
    if (res.status === 429) {
      const retryAfter = res.headers.get('Retry-After') || 60;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    return res;
  }
  throw new Error('Max retries exceeded');
}

404 Not Found​

Symptom: API returns 404 for ENS names or addresses.

Cause: The resource doesn't exist or isn't registered.

Common cases:

RequestCauseSolution
/api/ens/resolve/example.ethName not registeredCheck on ENS App
/api/ens/reverse/0x...No primary name setUser hasn't set reverse record
/api/farcaster/usernameUser doesn't existVerify on Warpcast
// Handle 404 gracefully
const res = await fetch(`https://api.web3identity.com/api/ens/resolve/${name}`);
if (res.status === 404) {
  console.log(`${name} is not registered`);
  return null;
}

500 Internal Server Error​

Symptom: API returns 500 unexpectedly.

Cause: Upstream data source issue or server error.

Solutions:

  1. Retry once — Transient errors often resolve
  2. Check status page — status.web3identity.com
  3. Try alternative endpoint — Use /api/smart/* endpoints with fallbacks
  4. Report issue — Email support@web3identity.com
// Use smart endpoints with built-in fallbacks
// Instead of:
fetch('https://api.web3identity.com/api/price/coingecko/ETH')

// Use:
fetch('https://api.web3identity.com/api/smart/price/ETH')
// Automatically falls back to alternative sources

CORS Errors​

Symptom: Browser console shows CORS errors.

Cause: Browser security blocking cross-origin requests.

Solutions:

The API has CORS enabled for all origins. If you see CORS errors:

  1. Check URL — Ensure you're using https://api.web3identity.com
  2. Check headers — Don't set Origin header manually
  3. Use fetch correctly — Don't use mode: 'no-cors'
// Correct usage
const res = await fetch('https://api.web3identity.com/api/ens/resolve/vitalik.eth');

// Wrong - don't do this
const res = await fetch(url, { mode: 'no-cors' }); // ❌ Can't read response

x402 Payment Issues​

Symptom: Payment header rejected or payment not settling.

Common causes:

IssueCauseSolution
"Invalid signature"Wrong message signedUse EIP-712 typed data signing
"Insufficient balance"Not enough USDCFund wallet on Base network
"Payment expired"Took too longPayment valid for 5 minutes
"Wrong network"Not on BaseSwitch to Base (chain ID 8453)
// Verify you're on Base network
const chainId = await provider.getNetwork().then(n => n.chainId);
if (chainId !== 8453n) {
  throw new Error('Please switch to Base network');
}

// Check USDC balance
const usdc = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, provider);
const balance = await usdc.balanceOf(walletAddress);
console.log(`USDC balance: ${ethers.formatUnits(balance, 6)}`);

SDK Issues​

"Module not found"​

# Ensure package is installed
npm install @atv-eth/x402-sdk

# Check it's in package.json
cat package.json | grep x402-sdk

"fetch is not defined" (Node.js < 18)​

// Add node-fetch for older Node versions
import fetch from 'node-fetch';
globalThis.fetch = fetch;

// Then import SDK
import { ATVClient } from '@atv-eth/x402-sdk';

TypeScript errors​

# Ensure TypeScript types are installed
npm install -D typescript @types/node

# SDK includes built-in types - no additional install needed

Debugging Tips​

Enable Verbose Logging​

// Log all requests
const originalFetch = globalThis.fetch;
globalThis.fetch = async (url, opts) => {
  console.log(`[API] ${opts?.method || 'GET'} ${url}`);
  const start = Date.now();
  const res = await originalFetch(url, opts);
  console.log(`[API] ${res.status} in ${Date.now() - start}ms`);
  return res;
};

Check Response Headers​

const res = await fetch('https://api.web3identity.com/api/ens/resolve/vitalik.eth');

// Useful headers
console.log('Rate limit remaining:', res.headers.get('X-RateLimit-Remaining'));
console.log('Cache status:', res.headers.get('X-Cache'));
console.log('Response time:', res.headers.get('X-Response-Time'));

Test with cURL​

# Verbose output
curl -v https://api.web3identity.com/api/ens/resolve/vitalik.eth

# See headers only
curl -I https://api.web3identity.com/api/health

# Pretty print JSON
curl -s https://api.web3identity.com/api/ens/vitalik.eth | jq

Still Stuck?​

  1. Check status page: status.web3identity.com
  2. Search docs: Use the search bar (press /)
  3. Review FAQ: /resources/faq
  4. Email support: support@web3identity.com
  5. Twitter: @ATV_eth

Report a Bug​

Include this information when reporting issues:

- Endpoint: /api/...
- Request: curl command or code snippet
- Response: Full error response
- Timestamp: When the error occurred (UTC)
- Your IP: (if rate limit issue)