RateLimit Headers (draft-ietf-httpapi-ratelimit-headers)

What are RateLimit Headers?

RateLimit Headers are standard HTTP response headers (IETF draft draft-ietf-httpapi-ratelimit-headers) that inform clients about current request limits. AI agents use these headers to self-regulate request pacing without triggering 429 Too Many Requests errors.

HTTP/1.1 200 OK
RateLimit-Policy: "sliding";q=100;w=60
RateLimit: "sliding";r=87;t=42
Retry-After: 30

Why do you need RateLimit Headers?

AI agents operating autonomously can generate a large number of requests in a short period. Without RateLimit headers, an agent only learns about a limit from a 429 error — after it’s already been blocked.

The headers give an agent three capabilities:

1. Proactive slowdown — when approaching the limit (the r = remaining field).
2. Retry planning — the exact wait time via Retry-After or the t (reset) field.
3. Strategy selection — parallel or sequential requests depending on available quota.

Especially important for MCP servers and APIs with usage-based pricing plans.

How do you implement RateLimit Headers?

The modern specification uses structured headers (RFC 8941). Two main headers:

Header	Content	Example
RateLimit-Policy	Policy definition (quota, window)	"sliding";q=100;w=60
RateLimit	Current state (remaining, reset)	"sliding";r=87;t=42

Example for Express (middleware):

app.use((req, res, next) => {
  const remaining = rateLimiter.getRemaining(req.ip);
  const resetIn = rateLimiter.getResetSeconds(req.ip);

  res.set('RateLimit-Policy', '"sliding";q=100;w=60');
  res.set('RateLimit', `"sliding";r=${remaining};t=${resetIn}`);

  if (remaining <= 0) {
    res.set('Retry-After', String(resetIn));
    return res.status(429).json({ error: 'Too Many Requests' });
  }
  next();
});

How do we check RateLimit Headers?

The scanner sends a HEAD request to the site root (/) and looks for modern structured headers:

Condition	Result
Both RateLimit-Policy + RateLimit present	pass
Only one of the two	pass (with recommendation to add the second)
Both absent	neutral (informational)

Missing headers are not treated as an error: many sites intentionally hide them. The check is performed only against the site root — headers on API endpoints are not checked.