# 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 `limit` that fits your need, and let webhooks tell you about changes instead of polling for them ([Webhooks and the signature](/guides/webhooks-and-the-signature/)).
- Spread background work over the day: several integrations under one group share the group lane.
- Treat `retryable: true` as 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](/guides/authentication-and-key-hygiene/)).