Rate limits
Calls are metered so the service stays responsive for everyone. Two counters watch an integration; when one is exceeded the call is refused before any work is done, with a wait you can read. This guide is the counters, the refusal, and how to stay under.
Two counters, one window
Every authenticated call counts once against two lanes over a fixed 60-second window: your session — the token you exchanged — and your organization group as a whole, across every API session it holds. An API session may make 300 calls per window; all the API sessions of your group together may make 600. The session lane is checked first, and a refusal there does not spend the group's budget. Each window is a fresh count — nothing carries over.
The refusal
Over the cap, the call answers RATE_LIMIT/THROTTLED: retryable is true, and detail names the lane that refused and retryAfterSeconds — the seconds until the window rolls. Wait that long, then send the same call again; sending sooner only repeats the refusal. The refusal is answered before the operation runs, so nothing was changed.
Staying under
- Exchange once and keep the session for its life (24 hours) — an exchange per call burns the sign-in lane, which pauses after repeated failures.
- Page with a
limitthat fits your need, and let webhooks tell you about changes instead of polling for them (Webhooks and the signature). - Spread background work over the day: several integrations under one group share the group lane.
- Treat
retryable: trueas an instruction to wait, never to hurry.
A bare 429 at the edge
A shared edge limit sits in front of the API. Under a sudden burst it may answer a bare HTTP 429 with no errors list and no envelope. Treat any 429 without an envelope as a rate refusal: back off for a moment, then retry with the same body.
The sign-in lane
The key exchange has its own, tighter throttle: repeated failed exchanges pause the lane for a while — RATE_LIMIT/LOGIN_LOCKED, retryable after the pause — whether or not the key exists. Store the secret once and exchange rarely (Authentication and key hygiene).