Rate limits
Per-key request rate limits, response headers, and how to handle 429s
API requests are rate-limited per API key. The exact limits depend on your plan and the kind of operation. Treat the headers on every response as the source of truth — don't hard-code limits in your client.
Categories
Limits are scaled by request category:
| Category | Notes |
|---|---|
Read (GET) | Highest ceiling. Listing, fetching, status checks. |
Mutation (POST / PUT / DELETE / PATCH) | Lower ceiling than reads. |
Analysis create (POST /v1/analyses) | Lowest ceiling — analyses are expensive to run. |
Higher plans get higher ceilings in every category. The exact numbers are returned on every response in the headers below — that's the canonical source.
Response headers
Every response includes:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your current window's ceiling |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Read these and pace your client. They'll always tell you the truth about what's allowed right now.
When you hit the limit
Status 429, error code RATE_LIMITED, plus a Retry-After header:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Reset: 1714067860{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 12 seconds."
}
}Retry-After is in seconds. Sleep at least that long before retrying.
Best practices
- Read
X-RateLimit-Remainingand back off proactively when it gets low - For batch jobs, paginate with the maximum
limitto reduce request count - For polling, respect
Retry-Afterand use the SSE streaming endpoint where available - Cache read responses when their content is stable (project list, channel list)
- Use exponential backoff with jitter on retries; cap your retry budget