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/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 429s 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 and webhooks instead of polling.
- Use bulk endpoints and large pages (
limit=500on desk). - Spread batch jobs over time instead of running many requests in parallel.