Rate limits

How much you may send, and what to do when you hit the ceiling.

The numbers

The minute is a sliding window of six ten-second buckets. That means you cannot spend a whole minute's allowance in one second: the count looks at the last sixty seconds rather than resetting on the clock.

Webhook deliveries do not count — those are our outgoing requests, not yours.

Headers

Every response tells you what is left:

Watch X-RateLimit-Remaining and slow down before you run out — that beats hitting the wall.

When you hit it

A 429 and a Retry-After header in seconds:

{
  "error": {
    "code": "rate_limited",
    "message": "This key may make 300 requests per minute",
    "details": { "scope": "key", "limit": 300 },
    "request_id": "…"
  }
}

details.scope says whose ceiling it was: key is yours, company means the whole project — someone else is spending the allowance in parallel.

Wait the stated time and repeat. Do not retry immediately: that only extends the refusal.

How to stay under it

• Subscribe to [webhooks](/en/guides/webhooks/) instead of polling. One event beats a thousand empty «anything new?» requests.
• Use `updated_since`. If you must poll, ask only for changes.
• Take pages of 100. The same data in a tenth of the requests.
• Do not fetch each row separately. A list already carries whole objects; a follow-up request per row is the most common way to hit the ceiling.