RateLimit-Reset

General Summary

Standardized header specifying when the current rate limit window will reset and the quota will be replenished.

Detailed Description

The RateLimit-Reset response header is the IETF standardized version of X-RateLimit-Reset. It 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 the number of seconds until reset.

X-RateLimit-Reset Legacy version of this header with X- prefix

Use Cases (When, Why, and How)

When to Use It

Modern APIs should include this standardized header in all rate-limited responses, particularly in 429 Too Many Requests responses. Prefer this over the legacy X-RateLimit-Reset header.

Why to Use It

The standardized header follows current HTTP specifications and ensures interoperability with modern API clients. It eliminates the need for clients to guess when to retry after being rate limited.

How to Use It

The server sets this header to either a Unix timestamp or the number of seconds until reset. 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('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

RateLimit-Reset: 1712275200