Understanding Rate Limit HTTP Headers

Rate Limit HTTP Headers

Rate limit headers are the primary way APIs communicate their rate limiting state to clients. Understanding these headers is essential for building resilient API integrations.

Standard Headers (IETF Draft)

The IETF has a draft standard (RFC 6585 + draft-ietf-httpapi-ratelimit-headers) proposing standardized headers:

Header	Description	Example
RateLimit-Limit	Maximum requests in window	100
RateLimit-Remaining	Requests left in window	87
RateLimit-Reset	Seconds until window resets	30
Retry-After	Seconds to wait (on 429)	60

Common Non-Standard Headers

Many APIs use the X- prefix (pre-standard) variants:

HTTP/1.1 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1706140800
X-RateLimit-Used: 13
X-RateLimit-Resource: core

Reset Value Interpretation

The Reset header is interpreted differently by different APIs:

API	Reset Format	Example	Meaning
GitHub	Unix timestamp	1706140800	Resets at this timestamp
Stripe	Seconds remaining	1	Resets in 1 second
Twitter	Unix timestamp	1706140800	Resets at this timestamp
Shopify	Unix timestamp	1706140800	Resets at this timestamp

Client Implementation Pattern

On every API response:
  1. Parse rate limit headers
  2. Store limit, remaining, reset values
  3. If remaining / limit < 0.2:
     -> Slow down request rate
  4. If remaining == 0:
     -> Sleep until reset time
  5. If response is 429:
     -> Read Retry-After header
     -> Exponential backoff: wait(min(Retry-After, 2^attempt))

Common Pitfalls

1. Clock skew: Do not compare server timestamps with local time. Use the delta between response Date header and Reset header.
2. Multiple windows: Some APIs enforce multiple rate limits simultaneously (per-second AND per-hour). Check all limit headers.
3. Shared limits: API keys may share limits across multiple applications. Monitor from a central point.