Rate Limits

Rate limiting caps how many requests your API key can send to OP Mainnet in a given window. TheRPC applies it to keep the service fast and fair for everyone and to protect the shared OP Stack infrastructure from spikes. Limits are enforced at several levels — per-second, per-minute, and per-day request counts, plus a ceiling on concurrent connections. The exact numbers depend on your subscription plan and are always visible in the dashboard, so you can see where you stand before you hit a wall.

Error Responses

When you exceed a limit on OP Mainnet, TheRPC returns a JSON-RPC error with code -32029 and the message "Rate limit exceeded" instead of a result. Alongside it, the HTTP response carries rate-limit metadata in its headers — X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset — so your client can see how much budget is left and when the window 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 OP Mainnet workload comfortably under the limits. First, retry rate-limited requests with exponential backoff so transient -32029 errors recover on their own. Second, batch independent reads into a single JSON-RPC request to cut round trips. Third, replace polling with WebSocket subscriptions via eth_subscribe so you receive new ~2-second blocks and logs as pushes instead of repeatedly asking. 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 OP Mainnet, eth_subscribe over WebSocket eliminates polling overhead entirely: instead of hammering the endpoint for the latest block every couple of seconds, you open one persistent connection and the server pushes newHeads and matching logs to you as they happen. That dramatically lowers your request count and keeps you well under your rate limit. See the eth_subscribe reference for subscription types and examples.

Monitoring

• Dashboard metrics — track your OP Mainnet request volume and remaining quota over time in the TheRPC dashboard.
• Rate-limit response headers — read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on each response to throttle in real time.
• Usage alerts — set up alerts so you're notified before you approach your plan's limits rather than after.

Quota Management

Manage your OP Mainnet quota programmatically by reading the rate-limit headers off each response — X-RateLimit-Remaining tells you how many calls are left and X-RateLimit-Reset when the window rolls over, so your client can pace itself instead of blindly retrying. Pair that with response caching: values that change slowly, like contract bytecode from eth_getCode or a confirmed receipt, can be cached locally so you don't re-fetch them, cutting your request volume and stretching your quota further.

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 across several dimensions for OP Mainnet: the request rate per second, the daily request 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 queries, the debug_ methods, and the trace_ API — which are essential for indexers and analytics on the Superchain. Compare the tiers side by side on the pricing page to find the right fit.

Upgrade Options

• Optimize your requests — batch independent reads and drop calls you don't need so each OP Mainnet request earns its keep.
• Add caching — store slowly-changing data locally to avoid re-fetching it.
• Switch to WebSocket subscriptions — replace polling with eth_subscribe to slash request counts for real-time data.
• Upgrade your plan — if you consistently hit limits, move to a higher tier for more throughput and access to archive, debug, and trace features.