Rate limits
What happens when you send too many requests, and how to recover.
Requests are rate limited. Short bursts of about 20 requests are allowed, above
a sustained rate of roughly 10 requests per second. Go beyond that and you get
429 Too Many Requests.
Treat the limit as a ceiling to stay under, not a target to hit.
Handling 429
Back off exponentially with jitter, then retry. Two things make retries safe:
- Send an
Idempotency-Keyon every create, so a retry cannot create a second billable report. - Never retry in a tight loop. A burst is consumed in well under a second, and retrying immediately only extends the wait.
Staying under the limit
- Use bulk creation — one request carries up to 500 reports, where 500 separate calls would be throttled.
- Use webhooks instead of polling for results. Polling is the most common reason integrations hit the limit.
- Ask for larger pages rather than more requests.