Communicating Limits: Headers and 429 Responses — Rate Limiting, Quotas & Abuse Protection

Clients behave better when they can see limits. Return 429 Too Many Requests with Retry-After (seconds or HTTP date) and a Problem Details body. Expose remaining quota with the IETF HTTPAPI RateLimit-Policy and RateLimit headers (the draft standardizes structured fields; many APIs still use legacy X-RateLimit-Limit/Remaining/Reset). Document limits per endpoint/plan, and make SDKs honor them.

Rate-limit headers

Header	Meaning
Retry-After	When to retry (seconds or date) — RFC 9110
RateLimit-Policy	Quota policies: limit (q) per window (w) — IETF draft
RateLimit	Remaining (r) and seconds until reset (t) for a policy — IETF draft
X-RateLimit-*	Legacy de-facto headers (Limit/Remaining/Reset)

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Policy: "default";q=1000;w=60
RateLimit: "default";r=0;t=12

{"type": "https://api.example.com/problems/rate-limited", "title": "Rate limit exceeded",
 "status": 429, "detail": "1000 requests per 60 seconds for API key ak_…3f", "retry_after": 12}

# Legacy (still common, e.g. GitHub)
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791627600

Common pitfalls

429 without Retry-After (clients guess and hammer).
Leaking internal limiter details per user in public headers unnecessarily.
Inconsistent header formats across services.

Key points

429 + Retry-After + Problem Details
RateLimit-Policy/RateLimit headers
Document and honor in SDKs

Further reading: IETF draft: RateLimit header fields for HTTP

Practice questions

Why include Retry-After in a 429?

Answer

It tells clients exactly when to retry, preventing aggressive guessing and synchronized retry storms.

What's the difference between the RateLimit-Policy and RateLimit headers in the IETF draft?

Answer

RateLimit-Policy describes the quota policies (limit and window); RateLimit reports the current state (remaining units and time until reset) for those policies.