Rate limits
Two tiers — a per-token burst limit and a per-organization sustained limit — plus the headers that let you back off on the one that is actually binding.
Two tiers, two questions
| Tier | Limit | Protects |
|---|---|---|
| Per token, burst | 120 / minute | Latency. One runaway loop in one integration must not make the workspace slow for everyone else |
| Per organization, sustained | 10,000 / hour across all tokens | The shared database, from any one workspace |
The organization tier is keyed on the workspace rather than the token on purpose: otherwise minting a second token would be a way to double your quota, which is precisely what a per-token-only limit invites.
Tighter per-endpoint limits still apply on top — search is capped at 60/minute for everyone, token or not.
The headers
Every token-authenticated response carries the budget, not just the 429:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1756100000These describe whichever tier is currently binding — the one with the fewest requests left. So a client that backs off on the number it sees is always backing off on the limit that would actually have stopped it, without having to track two counters itself.
X-RateLimit-Reset is a Unix timestamp for when the binding window rolls over.
When you are limited
HTTP/1.1 429 Too Many Requests
Retry-After: 27{
"success": false,
"message": "Rate limit exceeded.",
"error": { "code": "RATE_LIMITED" }
}Wait Retry-After seconds. It is authoritative — a shorter retry is refused
again and consumes budget doing so.
Throttling runs before the scope and allowlist checks. A refused request still costs you budget, so a client cannot use rapid-fire rejected calls as a free way to probe which endpoints exist.
Staying under the limit
- Pull once, filter locally. One call for 200 tasks beats 200 calls for one.
- Sync with the changes feed, not a poll of every list endpoint.
- Take events instead of polling. A webhook costs you nothing against these limits.
- Spread scheduled work. If a nightly job and an hourly job both start on the hour, they compete for the same organization budget.