X-RateLimit-Remaining
The HTTP X-RateLimit-Remaining response header is an unofficial HTTP header indicating the number of requests remaining in the current rate limit window.
Usage
APIs and web services use X-RateLimit-Remaining to tell clients how many requests are still available before hitting the rate limit. The value decrements with each request. When the count reaches zero, the server begins rejecting requests with a 429 status code until the rate limit window resets.
This header works alongside two companion headers: X-RateLimit-Limit (the total number of requests allowed per window) and X-RateLimit-Reset (the time when the window resets). Together, these three headers give clients enough information to pace their requests and avoid being throttled.
The header is a de facto standard adopted by major
API providers. GitHub and many other REST APIs
implement the same general pattern, though header
name casing varies (e.g., X-Ratelimit-Remaining,
X-RateLimit-Remaining).
The IETF is standardizing rate limit headers through the
RateLimit Fields for HTTP
draft. The current draft does not define a
RateLimit-Remaining header. Instead, remaining quota
is expressed as the r parameter within the RateLimit
field, alongside a t parameter for the seconds
remaining until reset.
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
The value is a non-negative integer representing the number of requests the client is allowed to make before the rate limit resets. The count starts at the value of X-RateLimit-Limit and decreases by one with each successful request.
Some APIs return fractional values when using weighted or tiered rate limiting, where different endpoints consume different amounts of the quota.
Example
A response showing 499 requests remaining out of a 500-request window. The client has made one request so far in this window.
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1771274193
A response from an API with a smaller rate limit. Only 12 requests remain out of 60 allowed per minute.
X-RateLimit-Remaining: 12
When the remaining count reaches zero, the next request triggers a 429 response. The Retry-After header often accompanies the response to indicate when the client is allowed to retry.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1771524477
Retry-After: 30
Takeaway
The X-RateLimit-Remaining header communicates how many API requests a client has left in the current rate limit window. Clients use this value to throttle their own request rate and avoid hitting 429 responses.