Rate Limits

GuidesUpdated June 14, 2026

Rate Limits

The API enforces a per-key rate limit using a sliding window. Limits apply per API key across all endpoints. The default limit is 120 requests per 60-second window (subject to change; always read the response headers rather than hard-coding the number).

Headers

Authenticated responses normally include rate-limit headers:

HeaderDescription
X-RateLimit-LimitMax requests allowed in the current window.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp (seconds) when the window resets.

If the rate-limiting backend is temporarily unavailable, most read endpoints fail open (the request is allowed) and the X-RateLimit-* headers may be absent on that response. Treat missing headers as "no limit info this time," not as an error.

When the limit is exceeded, the API returns 429 with error code RATE_LIMITED and a Retry-After header (seconds):

{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry in 12s.",
  "detail": { "limit": 120, "retry_after": 12 },
  "request_id": "..."
}

Two distinct 429s

  • RATE_LIMITED – HTTP-level per-key throughput limit (this page). Honor Retry-After.
  • WORKSPACE_LIMIT – A workspace quota was hit: too many concurrent batch jobs (returned by generate-batch), or a storage / lifetime-upload limit (returned by document imports). Retry after some jobs complete or free up quota.

Recommendations

  • Honor Retry-After and back off; do not retry tightly in a loop.
  • For single-lead generate: One request can take 3–10 minutes. Use a long client timeout; do not retry aggressively.
  • For batch: Submit batches at a reasonable pace and poll list status at a sensible interval (e.g. every 10–30 seconds) until completed.

Related guides