Rate limits

The two budgets

Limits are keyed on the credential you present — a SHA-256 fingerprint of the whole secret, not its visible prefix — so two tokens on the same account get two independent budgets, and an unauthenticated call falls back to your IP address. There are two budgets:

300

requests per 5 minutes

The burst window. Covers reads and writes alike.

write-tier calls per hour

A separate, slower budget for anything that changes state.

The two are independent: a read-heavy integration will never exhaust the write budget, and a burst of writes cannot be hidden inside the larger request budget.

Headers

A 429 is never silent. It carries Retry-After in seconds, plus the full X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset set, so a client can back off precisely instead of guessing.

GET /me reports the live request budget — limit, remaining, resetInSeconds, windowMinutes — without spending a meaningful part of it. It does not report the write-tier budget; the only signal for that one is the headers on the write itself.

Backing off

Global caps

Some operations have a system-wide daily cap on top of the per-token limits — restoring a backup, for instance. Those caps are not per token: they bound the total damage possible in a day regardless of how many tokens exist.

Hitting one returns 429 like any other limit, with a detail that says the cap is global rather than yours.

The other budget

If you are driving this API from a model, there is a second budget that matters more than requests per minute: context. Tool responses are capped at roughly 25,000 tokens by most clients, and a raw listing of a busy account blows straight through it.

limit defaults to 25; the ceiling is per-endpoint, and each reference page states its own. Take the default unless you know you need more.
Filter server-side — type, status, contains — instead of fetching everything and filtering locally.
Truncated responses say so and steer: "270 records; showing 25. Narrow with type or raise limit (max 200)."
Prefer the diagnostic endpoints over raw data where one exists. One diagnose call beats four listings and a guess.

let attempt = 0; while (attempt < 5) { const response = await fetch(url, { headers }); if (response.status !== 429) return response; // Honour Retry-After. It is authoritative — do not guess. const wait = Number(response.headers.get('Retry-After') ?? 2 ** attempt); await new Promise((resolve) => setTimeout(resolve, wait * 1000)); attempt += 1; } throw new Error('Rate limited five times in a row — stop and alert a human.');