Rate Limits

Rate limiting caps how many Bitcoin RPC requests you can send in a given window. TheRPC applies it to keep the shared Bitcoin endpoint fast and fair for everyone — without it, one noisy client polling the tip in a tight loop could degrade latency for all. Limits apply at several levels at once: requests per second, requests per minute, a daily quota, and a ceiling on concurrent connections. The exact numbers depend on your subscription plan and are shown in your dashboard, so check there for your current allowances rather than assuming a fixed figure.

Error Responses

When you exceed a limit, TheRPC returns a JSON-RPC error in the standard envelope with code -32029 and a "Rate limit exceeded" message — result is null, as shown below. Alongside the body, the HTTP response carries rate-limit metadata in headers: X-RateLimit-Limit (your ceiling for the window), X-RateLimit-Remaining (how many calls are left), and X-RateLimit-Reset (a Unix timestamp for when the window resets). Read these to pace yourself before you ever hit the error.

Rate Limit Error — JSON-RPC

1{
2  "result": null,
3  "error": {
4    "code": -32029,
5    "message": "Rate limit exceeded"
6  },
7  "id": "therpc"
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 limits. First, retry with exponential backoff when you see -32029, doubling the wait between attempts instead of retrying immediately. Second, batch independent calls into a single JSON-RPC array request so several reads count as one round trip. Third, choose sensible polling intervals — this matters most on Bitcoin because there is no WebSocket subscription RPC. You can't subscribe to new blocks; you poll the tip with getblockcount or getbestblockhash and react when it changes, so set that interval to the chain's rhythm rather than spinning as fast as possible.

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": "1.0",
4    "id": "1",
5    "method": "getblockcount",
6    "params": []
7  },
8  {
9    "jsonrpc": "1.0",
10    "id": "2",
11    "method": "getbestblockhash",
12    "params": []
13  }
14]

Sensible Polling Intervals

Bitcoin produces a block roughly every 10 minutes under proof-of-work, so polling the tip every second burns quota to learn nothing new the vast majority of the time. The efficient pattern is to poll getblockcount on a short interval only while you're actively waiting for the next block, cache the last value between polls, and act when the height increments. Outside an active wait, a much longer interval (tens of seconds or more) is fine — you'll still notice a new block well within its 10-minute lifetime.

Monitoring

• Dashboard metrics — your TheRPC dashboard shows request volume and quota consumption over time, the best place to see trends and spot anomalies.
• Rate-limit response headers — read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on each response to track headroom in real time.
• Usage alerts — set alerts so you're warned as you approach a limit, before requests start getting rejected.

Quota Management

Read your remaining quota programmatically from the response headers — X-RateLimit-Remaining against X-RateLimit-Limit — and slow down or pause when headroom runs low, as the tracking helper below shows. Caching is the other big lever: a lot of Bitcoin data never changes once it's confirmed. A confirmed block and its transactions are immutable, so cache them indefinitely and never re-fetch the same block hash. Cache slow-moving reads like getblockcount for a short window between polls, and you'll cut request volume sharply without losing freshness.

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 getCachedBlockCount(cacheTime = 30000) {
4  const cached = cache.get('blockCount');
5  if (cached && Date.now() - cached.timestamp < cacheTime) {
6    return cached.value;
7  }
8 
9  const newValue = await rpc('getblockcount');
10  cache.set('blockCount', {
11    value: newValue,
12    timestamp: Date.now(),
13  });
14 
15  return newValue;
16}

Plan Limits

Plans differ along three axes: the request rate you're allowed, your daily quota, and how many concurrent connections you can hold open. Beyond raw counts, heavier reads carry more weight — getblock at verbosity 2 or 3 and a verbose getrawmempool return far larger payloads than a simple getblockcount, so they consume more of your allowance and some may be gated to higher plans. Compare what each tier includes on the pricing page and pick the one that matches your read mix and volume.

Upgrade Options

• Optimize your requests — batch independent calls, drop redundant reads, and avoid pulling verbose mempool dumps on a loop.
• Add caching — store confirmed blocks and transactions permanently and short-lived reads like getblockcount for a few seconds.
• Widen polling intervals — match your tip-polling cadence to Bitcoin's ~10-minute block time instead of polling every second.
• Upgrade your plan — if you've tuned the above and still hit limits regularly, move to a tier with a higher rate, larger daily quota, and more concurrent connections.