X-RateLimit-Remaining

General Summary

Shows how many requests the client has left before hitting the rate limit threshold.

RateLimit-Remaining Standardized version of this header without X- prefix

Detailed Description

The X-RateLimit-Remaining response header indicates the number of requests remaining in the current rate limit window before the client will be throttled. This header decrements with each request made and resets when a new rate limit window begins. It provides real-time feedback to clients about their current quota consumption, enabling them to make informed decisions about request pacing and retry strategies.

Use Cases (When, Why, and How)

When to Use It

APIs should include this header alongside X-RateLimit-Limit in every response where rate limiting applies. It is especially critical in responses that are approaching the rate limit threshold or when the client has already been rate limited.

Why to Use It

Without visibility into remaining quota, clients must guess when they might hit rate limits, leading to unnecessary 429 errors and degraded user experiences. This header enables intelligent client behavior such as request queuing, adaptive throttling, and graceful degradation when quota is running low.

How to Use It

The server calculates the remaining requests for the client (based on IP address, API key, or user account) and includes this value in the response. Clients should monitor this value and implement backoff logic when it approaches zero.

Example code in Javascript:

async function makeRequest(url) {
  const response = await fetch(url);
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));

  if (remaining < 10) {
    console.warn('Approaching rate limit, slowing down requests');
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  return response.json();
}

Example

X-RateLimit-Remaining: 847