Rate limits

Rate limits are applied per API key, so one busy integration can't starve another. Read and write requests draw from separate budgets, and limits scale with the workspace's plan.

When you hit a limit

The request fails with 429 and the standard error envelope, plus a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded for this API key." } }

Backing off well

• Honor Retry-After — it reflects when your budget actually refills; guessing shorter just burns requests.
• Add jitter. If parallel workers all retry at the same instant, they collide again. Randomize within a window.
• Retry mutations with the same Idempotency-Key. A 429 can race a request that was actually admitted; the key guarantees the retry can't double-apply.
• Batch reads. Prefer one list call with limit=100 over a hundred single gets, and use webhooks instead of polling for changes.