Skip to main content
Rate limits keep one busy integration from slowing down everyone else. They apply per key, so two integrations with two keys never compete for the same allowance.

Limits

The limits are the same on every plan.
  • Every authenticated request counts, including /me, requests that end in 304 Not Modified, and requests refused with 403 for 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 gets 429 Too Many Requests:
Wait 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 with 429 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-Remaining gets low, sleep for X-RateLimit-Reset seconds before the next call instead of waiting for a 429.
  • Use the largest page. Pass limit=100 when 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-Match with the last ETag. A 304 still 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.
Last modified on November 18, 2026