X-RateLimit-Reset

General Summary

Specifies when the current rate limit window will reset and the quota will be replenished.

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

Detailed Description

The X-RateLimit-Reset response header indicates the exact time when the current rate limit window expires and the request quota will be restored to its maximum value. This is typically represented as a Unix timestamp (seconds since epoch) or an HTTP date string. When used together with X-RateLimit-Limit and X-RateLimit-Remaining, it provides clients with complete information needed to implement sophisticated retry and backoff strategies.

Use Cases (When, Why, and How)

When to Use It

Servers should include this header in all rate-limited responses, and it becomes critical in 429 Too Many Requests responses where clients need to know exactly when they can resume making requests.

Why to Use It

When a client exhausts their rate limit, they need to know precisely when to retry rather than continuously polling and wasting resources. This header eliminates guesswork and enables clients to schedule retries efficiently, reducing server load and improving the overall client experience.

How to Use It

The server sets this header to a Unix timestamp representing when the rate limit window resets. Clients should parse this value and wait until that time before making additional requests if they’ve been rate limited.

Example code in Javascript:

fetch('https://api.example.com/data')
  .then(response => {
    if (response.status === 429) {
      const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
      const waitSeconds = resetTime - Math.floor(Date.now() / 1000);
      console.log(`Rate limited. Retry in ${waitSeconds} seconds`);

      return new Promise(resolve => {
        setTimeout(() => resolve(fetch('https://api.example.com/data')), waitSeconds * 1000);
      });
    }
    return response.json();
  });

Example

X-RateLimit-Reset: 1712275200