Rate Limits

Rate limiting caps how many requests you can send in a given window. TheRPC applies it to your Base traffic to keep the service fast and fair for everyone and to protect the underlying nodes from overload. Limits are enforced at several levels at once — per second, per minute, and per day, plus a ceiling on concurrent WebSocket connections. The exact numbers depend on your subscription plan and are shown in your dashboard, so check there to see what your current key allows.

Error Responses

When you exceed a limit on Base, the API returns a JSON-RPC error with code -32029 and the message "Rate limit exceeded" (shown below). Alongside it, the HTTP response carries rate-limit metadata in headers — X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset — so your client can see how much quota is left and when it resets without guessing.

Rate Limit Error — JSON-RPC

1{
2  "jsonrpc": "2.0",
3  "error": {
4    "code": -32029,
5    "message": "Rate limit exceeded"
6  },
7  "id": 1
8}

Rate Limit Response Headers

1X-RateLimit-Limit: 10
2X-RateLimit-Remaining: 0
3X-RateLimit-Reset: 1628696400

Best Practices

Three strategies keep your Base integration under its limits. First, retry rejected requests with exponential backoff so brief spikes recover on their own. Second, batch independent calls into a single request to cut round trips. Third, replace polling with WebSocket subscriptions for real-time data — a single stream of Base's ~2-second blocks costs far fewer requests than repeatedly asking for the latest state. The sections below show each in practice.

Implement Retries

1async function callWithRetry(method, params, maxRetries = 3) {
2  for (let i = 0; i < maxRetries; i++) {
3    try {
4      const response = await makeRequest(method, params);
5      return response;
6    } catch (error) {
7      if (error.code === -32029) {
8        // Rate limit exceeded
9        const backoffTime = Math.pow(2, i) * 1000;
10        await new Promise((resolve) => setTimeout(resolve, backoffTime));
11        continue;
12      }
13      throw error;
14    }
15  }
16  throw new Error('Max retries exceeded');
17}

Batch Requests

1[
2  {
3    "jsonrpc": "2.0",
4    "method": "eth_getBalance",
5    "params": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "latest"],
6    "id": 1
7  },
8  {
9    "jsonrpc": "2.0",
10    "method": "eth_blockNumber",
11    "params": [],
12    "id": 2
13  }
14]

Use WebSocket Subscriptions

For real-time data on Base, eth_subscribe over WebSocket removes polling overhead entirely: instead of asking for the latest block every couple of seconds, you open one connection and the server pushes new heads, logs, and pending transactions as they occur. This drastically lowers your request count while delivering updates faster. See the eth_subscribe reference for subscription types and examples.

Monitoring

• Dashboard metrics — track your Base request volume, error rates, and quota consumption over time in the TheRPC dashboard.
• Rate-limit response headers — read X-RateLimit-Remaining and X-RateLimit-Reset on each response to see live quota in your code.
• Usage alerts — set up notifications so you hear about approaching limits before requests start failing.

Quota Management

Manage your Base quota programmatically by reading the rate-limit headers off every response — X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset — and slowing down before you hit zero (the helper below shows the pattern). You can also cut request volume with caching: data that changes slowly or never — chain ID, deployed contract bytecode, and finalized historical blocks — can be cached locally so you never re-fetch it, leaving your quota for live reads.

Track Usage

1function trackApiUsage(response) {
2  const limits = {
3    limit: response.headers['X-RateLimit-Limit'],
4    remaining: response.headers['X-RateLimit-Remaining'],
5    reset: response.headers['X-RateLimit-Reset'],
6  };
7 
8  console.log(`API calls remaining: ${limits.remaining}/${limits.limit}`);
9}

Implement Caching

1const cache = new Map();
2 
3async function getCachedBlockNumber(cacheTime = 5000) {
4  const cached = cache.get('blockNumber');
5  if (cached && Date.now() - cached.timestamp < cacheTime) {
6    return cached.value;
7  }
8 
9  const newValue = await web3.eth.getBlockNumber();
10  cache.set('blockNumber', {
11    value: newValue,
12    timestamp: Date.now(),
13  });
14 
15  return newValue;
16}

Plan Limits

Plans differ on the limits that matter for Base workloads: request rate, daily quota, the number of concurrent WebSocket connections, and how many active subscriptions you can hold. Higher tiers also unlock heavier capabilities — archive data for historical state, the debug_ methods, and the trace_ API — which are essential for indexers, analytics, and forensic work but gated on lower plans. Compare tiers side by side on the pricing page to pick the one that fits your traffic.

Upgrade Options

• Optimize your requests — batch independent calls and drop any redundant reads from your Base code.
• Add caching — store slowly-changing data like chain ID, contract code, and finalized blocks instead of re-fetching.
• Switch to WebSocket subscriptions — replace polling with eth_subscribe to slash request count.
• Upgrade your plan — if you still hit limits regularly, move to a higher tier for more throughput and quota.