Rate Limits

Rate limiting caps how many requests your API key can send to the Polygon endpoint over a given window. TheRPC applies it to keep the service fast and fair for everyone and to protect the infrastructure behind chain ID 137 from overload. Limits operate at several levels at once — per second, per minute, per day, and on concurrent connections — so a burst and a sustained load are both bounded. The exact numbers depend on your subscription plan and Compute Unit allowance, and you can see your current limits and usage at any time in the dashboard.

Error Responses

When you exceed a limit on the Polygon endpoint, TheRPC returns a JSON-RPC error with code -32029 and a "Rate limit exceeded" message instead of your 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, and back off accordingly.

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 you comfortably under your Polygon limits. Retry failed calls with exponential backoff so a brief -32029 does not cascade into more failures. Batch several reads into one JSON-RPC array to cut round trips. And replace polling loops with WebSocket subscriptions for real-time data, which on Polygon's ~2-second blocks dramatically reduces the request count. 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, eth_subscribe over the WebSocket endpoint replaces repeated polling with a push stream — the server notifies you when a new Polygon block or matching log appears, so you stop spending requests asking "anything new yet?" every couple of seconds. This is the single biggest win for staying under rate limits on a fast chain like Polygon. See the eth_subscribe reference for the available subscription types and examples.

Monitoring

• Dashboard metrics — track your Polygon request volume and Compute Unit usage over time in the TheRPC dashboard.
• Response headers — read X-RateLimit-Remaining and X-RateLimit-Reset on each response to see live budget per key.
• Usage alerts — set up alerts so you are notified before you approach your plan's limits, not after requests start failing.

Quota Management

You can manage your quota programmatically by reading the X-RateLimit-* headers off each Polygon response and adapting — throttling or pausing as X-RateLimit-Remaining approaches zero, and resuming after X-RateLimit-Reset. Pairing this with response caching cuts request volume further: data that changes slowly, like a finalized block or a contract's bytecode on chain ID 137, can be cached and reused instead of re-fetched on every call.

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 along several axes: request rate, daily quota, the number of concurrent WebSocket connections, and how many active subscriptions you can hold. Higher-tier plans also unlock the heavier Polygon capabilities — archive data for historical state queries on chain ID 137, the debug_ methods, and the trace_ API for full internal call trees. Compare the tiers and their Compute Unit allowances on the pricing page to find the right fit for your workload.

Upgrade Options

• Optimize requests — batch reads and trim any redundant calls to your Polygon endpoint.
• Add caching — store slowly-changing results so you re-fetch only what actually changed.
• Switch to WebSocket subscriptions — replace polling with eth_subscribe to slash request count on Polygon's ~2-second blocks.
• Upgrade your plan — move to a higher tier for more Compute Units, throughput, and concurrent connections.