Rate Limits

Rate limiting caps how many requests your key may send in a given window. TheRPC applies it to keep the Solana cluster responsive and to share capacity fairly across users, since Solana's high throughput means a single client can otherwise flood the node. Limits work at several levels at once: per-second and per-minute request rates, a per-day quota, and a ceiling on concurrent WebSocket connections. Not every call costs the same — heavy methods such as getProgramAccounts (which scans a program's entire account set) and getBlock (which can return thousands of transactions) carry more weight than a quick getSlot or getBalance. The exact numbers depend on your subscription plan and are shown in your dashboard.

Error Responses

When you exceed a limit, the request is rejected with a JSON-RPC error carrying code -32029 and a "Rate limit exceeded" message rather than a result. Alongside that, 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 headroom 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 you comfortably under the limits. First, retry with exponential backoff so a transient -32029 resolves itself instead of failing the whole flow. Second, batch independent reads into a single JSON-RPC array request to cut round trips. Third, replace polling with WebSocket subscriptions so you receive pushed updates 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    "id": 1,
5    "method": "getBalance",
6    "params": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
7  },
8  {
9    "jsonrpc": "2.0",
10    "id": 2,
11    "method": "getSlot",
12    "params": []
13  }
14]

Use WebSocket Subscriptions

For real-time data, lean on the WebSocket PubSub endpoint instead of polling. accountSubscribe pushes you an update whenever a watched account changes, logsSubscribe streams transaction logs matching a filter, and slotSubscribe notifies you as each new slot is processed — none of which consume request-rate budget the way a polling loop would. See the WebSocket subscriptions guide and the accountSubscribe reference for setup and message handling.

Monitoring

• Dashboard metrics — track request volume, error rates, and quota consumption per key in your TheRPC dashboard.
• Rate-limit response headers — read X-RateLimit-Remaining and X-RateLimit-Reset on each HTTP response to throttle yourself before hitting -32029.
• Usage alerts — set up alerts so you're notified as you approach your plan's quota rather than discovering it after requests start failing.

Quota Management

Manage quota by reading the rate-limit headers programmatically: parse X-RateLimit-Remaining and X-RateLimit-Reset off each response so your code can slow down or pause before it trips the limit, as the tracking helper below shows. You can also cut request volume sharply by caching data that rarely changes. Values like getEpochSchedule, getGenesisHash, and getVersion are effectively constant for an endpoint, so fetch them once and reuse them instead of asking on every request; even fast-moving reads like getSlot can be cached for a short window when approximate freshness is acceptable.

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

Plan Limits

Plans differ across several dimensions: the allowed request rate, the daily quota, the number of concurrent WebSocket connections, and how many active subscriptions you may hold. Higher tiers also unlock deeper capabilities — archival history, so getBlock and getSignaturesForAddress can reach far older slots beyond the recent window, and headroom for heavy scans like getProgramAccounts. Compare the tiers side by side on the pricing page to find the plan that matches your Solana workload.

Upgrade Options

• Optimize requests — batch independent calls and use getMultipleAccounts instead of many getAccountInfo; narrow getProgramAccounts with filters.
• Add caching — store slowly-changing values like getGenesisHash and getEpochSchedule instead of refetching.
• Switch to WebSocket subscriptions — replace polling loops with accountSubscribe, logsSubscribe, or slotSubscribe.
• Upgrade your plan — move to a higher tier for more request rate, daily quota, connections, and archival access.