Rate limits & concurrency

Jobs and capacityCopy Anchor Link

Each request runs as one job.

• No capacity free. When none is available the API answers 503 with reason: no_capacity. Retry after a pause.
• Attempts. A job gets up to 5 attempts (8 for Google AI Overview, Google AI Mode and ChatGPT) before the API answers.
• Timeout. A request with no answer by about 95 seconds gets 500 with reason: job_timeout. Set your client timeout to about 100 seconds.

Staying within capacityCopy Anchor Link

Retry 503 with a growing pause rather than immediately, and do not send more requests than you need. If you cancel work you no longer want, use GET /v1/cancel (see Errors & billing).

Per-key limitsCopy Anchor Link

Each API key belongs to a plan. The plan sets how many requests the key can make each month and how many it can have in flight at once.

Monthly requests reset on your billing date. Only 200 and 404 answers count; see Errors & billing. Every 200 carries X-RateLimit-Remaining, the calls left on your key.

• Too many at once. Concurrency is how many requests a key may have in progress at once, not a per-second limit. A request beyond it is refused with 429 Concurrent request limit exceeded straight away and isn't charged. There is no Retry-After. The response carries RateLimit-Limit (your limit) and RateLimit-Remaining (free slots, not your call balance). Retry when one of your requests finishes, or after a second or two.
• Out of requests. When the month's requests are used up, the API answers 403 with the error API call quota exceeded until the next billing date or a plan upgrade. A top-up is picked up on the next request.
• Order of checks. The key is checked first (401), then whether it is known (403), then concurrency (429), then quota (403). A key that is at its concurrency limit and out of quota gets 429.
• Sizing your client. Run at most as many parallel requests as your plan's concurrency limit. With Enterprise, that's 50 at once.

Need more volume or concurrency? Contact us for a custom plan.