Rate limits

Every call to the v1 API counts against two rate-limit buckets:

• A per-token limit (the service account’s own usage).
• A per-organization limit (everything happening across all tokens issued by that workspace).

When either bucket is exhausted, the API responds with 429 Too Many Requests until the bucket refills.

Default limits

Default limits suit normal integration usage. They are deliberately conservative to protect the workspace from runaway integrations.

Integrations doing routine sync work do not come close to these. Bursty bulk backfills can hit them; coordinate large backfills with your account team in advance.

Headers

Every response (success or error) includes these headers so you can see where you stand:

Inspect X-RateLimit-Remaining to throttle proactively rather than waiting for 429.

Handling 429

When you get 429:

1. Honor the Retry-After header. Sleep for at least that many seconds before the next call.
2. Back off exponentially if you hit 429 repeatedly. Treat Retry-After as a minimum, not the only delay.
3. Pair retries with idempotency keys on write endpoints, so a retried call doesn’t accidentally double-process.

attempt = 1
while attempt <= 5:
  response = call_api(idempotency_key=key)
  if response.status != 429:
    return response
  delay = max(response.headers["Retry-After"], 2^attempt) + jitter
  sleep(delay)
  attempt += 1

Proactive throttling

A well-behaved integration treats X-RateLimit-Remaining as the steering signal, not 429:

• If Remaining is below 10% of Limit, slow down or batch.
• If Remaining is zero, do not call again until X-RateLimit-Reset.

This costs nothing and avoids the noise of 429 retries in your logs.

Limit increases

Most integrations should not need to ask for higher limits. If your use case genuinely requires more:

• Document the integration purpose, expected steady-state RPS, and burst characteristics.
• Talk to your account team. Limit increases are negotiated per-customer with the workspace’s commercial contact, not adjusted ad hoc.

What is and isn’t rate-limited

Heavy backfills

For one-time backfills:

• Time-spread by inserting deliberate sleeps between batches so you don’t burst against the per-minute limit.
• Chunk by resource so each request stays small.
• Use idempotency keys so a partial backfill can resume from the last successful item.
• Talk to your account team beforehand if the backfill is large enough to be visible in workspace metrics; we’d rather hear about it than throttle blindly.

Next

• Pagination
• Webhooks - for push-style integration that avoids polling rate limits entirely.