Reading RPC Rate-Limit Headers: X-RateLimit and Retry-After

Why reactive 429 handling is not enough

Most RPC clients only learn about rate limits when a request fails with HTTP 429. That is the expensive path: the throttled call still consumed a network round trip, still added to your p99 latency, and on many providers still counts against a stricter window, so a burst of 429s can extend the penalty. The how to fix RPC 429 errors playbook covers the reactive side — exponential backoff with jitter — but backoff alone is guessing.

Rate-limit headers are the proactive side of the same contract. Instead of inferring your budget from failures, the server tells you on every response how much allowance you have left and when it resets. A client that reads those fields can slow down, defer non-urgent work, or spread a burst before the first 429 ever happens.

This matters most for latency-sensitive paths. If your application polls account state or submits transactions on a schedule, a single 429 can push a whole batch past its deadline. Reading the headers lets you trade a small, controlled delay for avoiding a large, uncontrolled one.

• A 429 costs a round trip and often counts against a stricter window than the one you were pacing for.
• Headers let you pace before the limit, not after it.
• Proactive pacing protects p99 latency; reactive backoff only protects correctness.

The two header families: IETF RateLimit and legacy X-RateLimit

There are two naming families in the wild. The first is the IETF draft RateLimit Header Fields for HTTP, which defines RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset as structured fields. The second is the older de-facto convention X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, popularized by early public APIs and still widely used by RPC providers.

The semantics are the same in both families: Limit is the ceiling for the current window, Remaining is how much of that ceiling is left, and Reset is when the window rolls over. The difference is naming and, sometimes, the unit of Reset. Because header presence and naming are documented / varies by provider, a robust client should check both families on every response rather than assuming one.

Retry-After is a separate, older field defined in RFC 9110 (HTTP Semantics). It is most commonly sent with a 429 or 503 and tells you how long to wait before retrying. It is not a budget signal — it is an instruction.

• IETF draft family: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.
• Legacy family: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• Retry-After (RFC 9110) is an instruction sent with 429/503, not a budget field.

Parsing Reset and Retry-After without guessing

The single most common parsing bug is assuming a unit for Reset. Some providers send epoch seconds (a large number like 1757800000); others send delta seconds (a small number like 12). You can detect the form by magnitude: values above roughly 1e9 are almost certainly epoch seconds, while small values are deltas. Always convert to an absolute deadline before you use it.

Retry-After is defined by RFC 9110 to accept either delta-seconds or an HTTP-date. A value like 30 means wait 30 seconds; a value like Wed, 21 Oct 2026 07:28:00 GMT means wait until that instant. Parse both: if the value is all digits, treat it as seconds; otherwise parse it as a date and subtract the current time.

Treat a 429 Retry-After as authoritative over your own backoff. If the server says wait 30 seconds, waiting 2 seconds and retrying just burns another request and may extend the penalty. Only fall back to your own exponential backoff when Retry-After is absent.

• Reset: detect epoch vs delta by magnitude, then convert to an absolute deadline.
• Retry-After: digits mean seconds; anything else is an HTTP-date.
• Server Retry-After overrides client-side backoff when present.

Decision table for header values

Use this table to decide what a header value means before you act on it. The goal is to normalize every form into two numbers: remaining budget and seconds until reset.

Once normalized, your pacing logic only needs those two numbers plus the current time. That keeps the client simple and provider-agnostic.

• RateLimit-Remaining = 0, Reset in 5s → pause all non-urgent calls for 5s, then resume.
• RateLimit-Remaining = 5, Reset in 1s → safe to send a small burst now; the window is about to roll.
• RateLimit-Remaining = 5, Reset in 60s → spread the 5 calls across 60s; do not burst.
• Retry-After = 30 → wait 30s exactly, regardless of your own backoff schedule.
• Retry-After = HTTP-date → wait until that instant, computed as date minus now.
• No headers at all → fall back to conservative fixed pacing and measure your own ceiling.

Why the window model changes what Remaining means

Remaining = 5 does not mean the same thing under every limiter. Under a fixed window, the counter resets at a boundary, so a burst that fits just before the boundary is free. Under a sliding window, the counter reflects the last N seconds continuously, so the same burst can still be throttled even though Remaining looked healthy.

Token-bucket limiters are different again: they refill at a steady rate and allow a burst up to the bucket size. A client that only reads Remaining cannot distinguish these models, which is why the Reset value matters as much as the Remaining value. If Reset is far away and Remaining is low, you are near a hard ceiling; if Reset is near, the window is about to refresh.

The practical rule: pace to a sustainable rate derived from Remaining and Reset, and never assume a burst is safe just because Remaining is non-zero. For a deeper look at how limits interact with latency, see how to reduce RPC latency.

• Fixed window: bursts near the boundary are cheap.
• Sliding window: bursts are smoothed; Remaining can look healthy and still throttle.
• Token bucket: steady refill plus a burst allowance up to the bucket size.

Building a budget-aware client

A budget-aware client does three things on every response: reads the headers, computes a sustainable rate, and paces the next call. The sustainable rate is simply Remaining divided by seconds until Reset. If that rate is below what your workload needs, defer non-urgent calls rather than sending them and collecting 429s.

For bursts, use a token-bucket or leaky-bucket pacer in front of your RPC calls. The pacer releases requests at the sustainable rate and absorbs short spikes without exceeding the budget. When a 429 arrives with Retry-After, the pacer should drain and wait for the full interval before releasing anything.

This design also makes failover cleaner. If you run multiple endpoints, each has its own budget; a client that tracks Remaining per endpoint can shift load to the endpoint with headroom. The RPC node monitoring and failover guide covers the health-check side of that pattern.

• Sustainable rate = Remaining / seconds until Reset.
• Use a token-bucket or leaky-bucket pacer to spread bursts.
• Track budget per endpoint so failover can prefer the endpoint with headroom.

Which budget did you spend? Per-key, per-IP, per-method, per-connection

Headers tell you how much budget is left, but not always which budget. Providers may limit per API key, per source IP, per method weight, or per connection. A heavy method like eth_getLogs may cost more than a light one like eth_blockNumber, so a single Remaining counter can hide method-level weighting.

If you share an API key across services, one noisy service can exhaust the budget for all of them. If you share an IP behind a NAT or proxy, your budget may be pooled with unrelated traffic. Understanding which dimension you are spending helps you decide whether to split keys, add a dedicated endpoint, or move heavy methods to a separate path.

For provider-specific limits and plan details, see RPC pricing and the API service pages. Header presence and naming remain documented / varies by provider.

• Per-key: shared across all services using that key.
• Per-IP: pooled behind NAT or proxies.
• Per-method weight: heavy calls cost more than light ones.
• Per-connection: WebSocket connections may be limited separately from request budget.

Runnable Node.js example: log headers and pace the next call

This example uses the built-in fetch in Node.js 18+. It reads both header families, normalizes Reset, and waits before the next call if the budget is low. It also honors Retry-After on a 429.

Run it against your own endpoint and watch the logged values. The numbers you see are your endpoint's real behavior, not a benchmark.

// node --version >= 18
const RPC_URL = process.env.RPC_URL || 'https://your-endpoint.example';

function parseReset(value) {
  if (!value) return null;
  const n = Number(value);
  if (!Number.isFinite(n)) return null;
  // epoch seconds are large; delta seconds are small
  return n > 1e9 ? n * 1000 : Date.now() + n * 1000;
}

function readBudget(headers) {
  const get = (names) => {
    for (const name of names) {
      const v = headers.get(name);
      if (v !== null) return v;
    }
    return null;
  };
  const limit = get(['ratelimit-limit', 'x-ratelimit-limit']);
  const remaining = get(['ratelimit-remaining', 'x-ratelimit-remaining']);
  const reset = get(['ratelimit-reset', 'x-ratelimit-reset']);
  return {
    limit: limit ? Number(limit) : null,
    remaining: remaining ? Number(remaining) : null,
    resetAt: parseReset(reset),
  };
}

function parseRetryAfter(value) {
  if (!value) return null;
  if (/^\d+$/.test(value)) return Number(value) * 1000;
  const t = Date.parse(value);
  return Number.isFinite(t) ? Math.max(0, t - Date.now()) : null;
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(method, params) {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
  });

  const budget = readBudget(res.headers);
  console.log('status', res.status, 'budget', budget);

  if (res.status === 429) {
    const wait = parseRetryAfter(res.headers.get('retry-after')) ?? 1000;
    console.log('429 received, waiting', wait, 'ms');
    await sleep(wait);
    return null;
  }

  // pace the next call if budget is low
  if (budget.remaining !== null && budget.resetAt) {
    const msLeft = Math.max(0, budget.resetAt - Date.now());
    if (budget.remaining <= 1 && msLeft > 0) {
      console.log('low budget, waiting', msLeft, 'ms');
      await sleep(msLeft);
    }
  }

  return res.json();
}

(async () => {
  for (let i = 0; i < 10; i++) {
    await call('eth_blockNumber', []);
  }
})();

Measuring your endpoint's real ceiling with a controlled burst

Because header presence and limits vary by provider, the only reliable ceiling is the one you measure. Send a controlled burst, record the header values on each response, and note the request index at which the first 429 appears. Repeat at different times of day to see whether the limit is shared or dedicated.

Fill the table below with your own results. Do not treat any single run as definitive; the point is to derive a sustainable rate you can pace to, not to publish a benchmark.

• Results Table columns: request #, status, RateLimit-Remaining, RateLimit-Reset (raw), Reset (normalized), Retry-After, elapsed ms.
• Row 1–N: record until the first 429, then stop and note the index.
• Repeat the burst 3 times at different hours; compare the first-429 index.
• Derive sustainable rate = successful requests / elapsed seconds before the first 429.
• If headers are absent, record that too — it changes your fallback strategy.

Batching, WebSocket subscriptions, and connection limits

JSON-RPC batching can reduce round trips but does not necessarily reduce budget consumption: many providers count each call inside a batch against the limit, so a batch of 50 still spends 50 units. Read the headers after a batch to confirm how it was counted.

WebSocket subscriptions are different. A subscription does not consume request budget per message, but the number of concurrent connections may be limited separately. If you open many subscriptions, you may hit a connection cap rather than a request cap, and that cap may not be reflected in RateLimit-Remaining.

For endpoint selection and connection guidance, see the RPC endpoints guide. For network-specific context, see Ethereum RPC rate limits and 429s and the Ethereum network page.

• Batches often count per call, not per HTTP request.
• Subscriptions do not spend request budget but may hit a separate connection cap.
• Check headers after a batch to learn how your provider counts it.

Limitations and tradeoffs of header-driven pacing

Header-driven pacing is not free. It adds a small amount of client complexity, and it only works when the provider actually sends the headers. Some providers send them only on 429 responses, some strip them at a CDN or proxy, and some use different names entirely.

Pacing also trades throughput for stability. If you slow down to stay under the budget, you may finish a batch later than a client that bursts and retries. For latency-critical workloads, the right answer may be a higher-tier plan or a dedicated endpoint rather than tighter pacing.

Finally, headers describe the server's view of your budget, which may be shared with other traffic on the same key or IP. A client cannot see that sharing, so it should treat Remaining as an upper bound, not a guarantee.

• Requires provider support; header presence is documented / varies by provider.
• Trades throughput for stability; not always the right choice for latency-critical work.
• Shared keys or IPs mean Remaining is an upper bound, not a guarantee.

Troubleshooting: I never see the rate-limit headers

If the headers are missing, work through the likely causes in order. First, check whether they appear only on 429 responses — some providers send budget headers only when you are throttled. Second, check whether a CDN or reverse proxy is stripping them; cached responses in particular may not carry rate-limit fields.

Third, check the header names. Some providers use a vendor prefix or a different casing convention. Log all response headers once and inspect them rather than assuming a name. Fourth, confirm you are reading the response headers and not the JSON-RPC body, which never contains rate-limit fields.

If none of these apply, fall back to conservative fixed pacing and measure your own ceiling with the burst method above. The OnFinality Learn hub has related guides on 429 handling and endpoint monitoring.

• Headers only on 429 → treat 429 Retry-After as your primary signal.
• Stripped by CDN/proxy → test against the origin endpoint directly.
• Different name → log all headers once and inspect.
• Reading the body instead of headers → check res.headers, not res.json().
• No headers at all → use fixed pacing and measure your own ceiling.

Next steps: instrument, measure, then pace

Start by logging the headers on every response for a day. You will quickly see whether your provider sends them, which family it uses, and how Reset is expressed. That single change turns rate limiting from a mystery into a measurable signal.

Then run the controlled burst and fill the results table. Use the sustainable rate you derive to configure a token-bucket pacer, and treat any 429 Retry-After as authoritative. If you need more headroom than pacing can provide, review RPC pricing and the API service options, and consider a dedicated endpoint for heavy workloads.

For a broader view of endpoint selection and failover, see the RPC endpoints guide and RPC node monitoring and failover.

• Log headers for a day to learn your provider's contract.
• Measure your ceiling with a controlled burst and a results table.
• Configure a pacer from the sustainable rate; honor Retry-After on 429.