X-RateLimit-Reset
The HTTP X-RateLimit-Reset response header is an unofficial HTTP header indicating when the current rate limit window resets.
Usage
APIs and web services send X-RateLimit-Reset to tell clients when they will get a fresh allocation of requests. Once the reset time arrives, the request counter (tracked by X-RateLimit-Remaining) returns to the maximum value defined by X-RateLimit-Limit, and the client is free to resume normal request rates.
This header is a de facto standard adopted by GitHub, Twitter/X, Docker Hub, Shopify, and many other API providers. The value format is not consistent across implementations. Most APIs (GitHub, Docker Hub, DSpace repositories) send a Unix epoch timestamp in seconds. Some APIs send the number of seconds remaining until the window resets. A few send millisecond-precision timestamps.
The IETF is standardizing rate limit headers through the
RateLimit Fields for HTTP
draft. The current draft does not define a
RateLimit-Reset header. Reset timing is expressed as
the t parameter within the RateLimit field, using
seconds remaining (delta-seconds).
Note
The "X-" naming convention for HTTP headers, "X" referring to "experimental", has been deprecated and needs to be transitioned to the formal naming convention for HTTP headers.
Values
Unix timestamp
The most common format. The value is an integer representing the number of seconds since January 1, 1970 (Unix epoch). Clients compare this value against the Date header or their local clock to determine how long to wait.
Seconds remaining
Some APIs send the number of seconds until the
rate limit window resets, similar to the
Retry-After header format. A value
of 60 means the window resets in 60 seconds.
Example
A typical rate limit response group from an API
using Unix timestamps. The reset time 1771274193
is an absolute point in time (a Unix epoch value).
The client has 499 requests left out of 500
before the reset time arrives.
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1771274193
An API using seconds-remaining format. The rate limit window resets in 60 seconds from the time of the response.
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 60
When a client exhausts all remaining requests, the server responds with 429 and the reset header tells the client exactly when to retry. The Retry-After header often appears alongside for clients not aware of the X-RateLimit headers.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1771524477
Retry-After: 120
Takeaway
The X-RateLimit-Reset header tells API clients when their rate limit window resets, either as a Unix timestamp or as seconds remaining. Paired with X-RateLimit-Remaining and X-RateLimit-Limit, the header gives clients the information needed to schedule requests and avoid 429 responses.