# 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
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](/glossary/mcp-server-card) 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):

```typescript
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.

[← All glossary terms](/en/glossary)