Rate limits

Each key has its own window: 120 requests per 60 seconds by default. It is an operational abuse ceiling, not a plan quota. Usage itself is metered by the owner’s balance, not by this counter, and keys of the same owner do not share the window. Authentication runs before the limiter, so an unauthenticated request never spends a key’s budget.

Headers

Every response, success or failure, carries the state of the window:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix time (seconds) when the window resets

When the window is exhausted the API answers 429 rate_limit_exceeded and adds Retry-After (seconds).

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789470060
Retry-After: 17
X-Request-ID: 7f20a5f0-5dde-48cf-94aa-38acbbd218e0

{"error": {"code": "rate_limit_exceeded", "message": "Rate limit exceeded for this API key; try again later", "request_id": "7f20a5f0-5dde-48cf-94aa-38acbbd218e0"}}

When the limiter itself is down

The limiter fails closed. If its backing store is unavailable, the API answers 503 api_rate_limit_unavailable with Retry-After: 5 instead of letting requests through unmetered, and instead of a misleading 429. Treat it like any other transient error: wait and retry with the same Idempotency-Key.

Do not spread traffic across several keys of the same agent to lift the ceiling. Each key has its own conversations, so the same end user would end up with a fragmented history. If you need a higher limit, contact us.

Client-side pacing

import time

import httpx


def request_with_pacing(method: str, url: str, **kwargs) -> httpx.Response:
    while True:
        response = httpx.request(method, url, headers=HEADERS, timeout=120, **kwargs)
        if response.status_code in (429, 503):
            time.sleep(float(response.headers.get("Retry-After", "5")))
            continue
        if int(response.headers.get("X-RateLimit-Remaining", "1")) == 0:
            reset_at = int(response.headers.get("X-RateLimit-Reset", "0"))
            time.sleep(max(0.0, reset_at - time.time()))
        return response

async function requestWithPacing(url, init = {}) {
  for (;;) {
    const response = await fetch(url, {
      ...init,
      headers: { Authorization: `Bearer ${apiKey}`, ...(init.headers ?? {}) },
    });
    if (response.status === 429 || response.status === 503) {
      const wait = Number(response.headers.get("Retry-After") ?? 5);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (response.headers.get("X-RateLimit-Remaining") === "0") {
      const resetAt = Number(response.headers.get("X-RateLimit-Reset") ?? 0) * 1000;
      await new Promise((r) => setTimeout(r, Math.max(0, resetAt - Date.now())));
    }
    return response;
  }
}

Get Started

Guides

Headers

When the limiter itself is down

Client-side pacing

​Headers

​When the limiter itself is down

​Client-side pacing

Headers

When the limiter itself is down

Client-side pacing