# Rate limits

The APIs limit requests with a token bucket **per authenticated principal and route**: your key's
identity (personal key: its owner; service account: the account) and the endpoint template
(`GET /items/{ref}` counts separately from `GET /items`). Callers behind the same IP address do not
share a budget. A limit holds once for the whole platform, however many instances of a module serve
your requests.

| Scope | Sustained | Burst |
|---|---|---|
| HR, desk, forge and flows routes | 20 requests/s | 100 |
| Comms routes (per client address, not per principal) | 20 requests/s | 100 |
| Masterdata AI drafts (`…:draft`) | 1 request every 2 s | 20 |
| Masterdata imprint lookup `POST /imprint:lookup` | 1 request every 5 s | 10 |
| Key exchange `POST /auth/token` | limited per client address | |
| Comms inbound webhooks `POST /hooks/{publicId}` | 10 requests/s per client address | 50 |
| Requests without a valid token | limited per client address | |
| Other modules | see the module's reference (*Conventions*) | |

Desk bulk endpoints accept up to 200 items per request, so a bulk call is almost always better
than 200 single calls.

## When you exceed a limit

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{"error": "too many requests", "code": "rate_limited"}
```

`Retry-After` is the number of whole seconds until the bucket holds a request again (at least 1): a
route with 1 request every 5 s answers up to `5`. Wait that long, then continue. Back off
exponentially if `429`s repeat.

## Staying below the limits

- Cache the access token (one exchange per 15 minutes, not per request).
- Cache configuration (`bootstrap`) and refresh it only when you see unknown keys.
- Use [delta sync](/guides/pagination) and [webhooks](/guides/webhooks) instead of polling.
- Use bulk endpoints and large pages (`limit=500` on desk).
- Spread batch jobs over time instead of running many requests in parallel.
