Limits
The limits are the same on every plan.
- Every authenticated request counts, including
/me, requests that end in304 Not Modified, and requests refused with403for a missing scope. - REST and MCP share the allowance. Each MCP call made with a key counts against the same 300 requests as that key’s REST calls.
- Each window resets on the whole minute.
Headers
Successful responses (200 and 304), 403 insufficient_scope and key-level 429 responses carry:
X-RateLimit-Reset is a number of seconds, not a timestamp.
When you hit the limit
A key that runs out of requests gets429 Too Many Requests:
Retry-After seconds, then retry the same request. A 429 is answered before anything runs, so retrying it is safe for every endpoint, the facts writes included. For retries after a timeout or a 5xx, see Retry writes safely.
Failed authentication
Repeated failed authentications from one network are throttled with429 and Retry-After. Fix the key rather than retrying: a 401 won’t succeed on its own.
Handle 429 in code
Stay under the limit
- Pace bulk jobs. If
X-RateLimit-Remaininggets low, sleep forX-RateLimit-Resetseconds before the next call instead of waiting for a429. - Use the largest page. Pass
limit=100when you export whole lists. That’s half the requests of the default page size. - Don’t poll for changes. Subscribe to webhooks and fetch only when something happened.
- Revalidate instead of re-downloading. Send
If-None-Matchwith the lastETag. A304still counts as a request but returns no body. See Caching and request IDs. - One key per integration. Each key has its own 300-request allowance.
Next steps
Pagination
Page through large lists efficiently.
Errors
The full list of problem types and how to handle each.