Rate Limit Headers

Rate limit headers are HTTP response headers that inform API consumers about their current rate limit status on every response, not just when they've been throttled. The conventional headers are X-RateLimit-Limit (the maximum number of requests allowed in the current window), X-RateLimit-Remaining (how many requests the client has left), and X-RateLimit-Reset (when the rate limit window resets, typically as a Unix epoch timestamp). The IETF draft RFC 9110 proposes standardizing these as RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (using delta seconds instead of epoch).

Including these headers on every successful response -- not just 429 responses -- enables clients to implement proactive throttling. A well-behaved client can monitor its remaining quota and slow down before hitting the limit, resulting in smoother traffic patterns for both the client and the server. SDKs and client libraries often use these headers to implement automatic retry-with-backoff logic.

When a client exceeds the rate limit, the 429 Too Many Requests response should include a Retry-After header indicating how long the client should wait before retrying. This can be expressed as a delta in seconds or as an HTTP-date. Consistent header naming and value formats across all endpoints reduce confusion and make it easier for consumers to build robust integration logic.