Skip to main content
Rate-limit headers are returned on rate-limited routes. Master keys and UNLIMITED_API_KEYS bypass this limiter and may have no X-RateLimit-* headers. HTTP header names are case-insensitive: X-Ratelimit-Limit and X-RateLimit-Limit are equivalent. A new valid key first uses the IP bucket; after credential-cache warm-up it uses its personal limit (for example, 40 → 120 for stats). Retry-After is returned when limited. On the OpenAI-compatible /v1/* methods the same values use the OpenAI names: x-ratelimit-limit-requests, x-ratelimit-remaining-requests and x-ratelimit-reset-requests (time until reset, for example 1s). See the AI API overview.

​
429 response

When the limit is exceeded, the API responds with HTTP 429. The body has only the code and message; the wait time is in the headers:
If you keep sending requests after a 429, the key or IP is blocked for a while: you get code 5039, and Retry-After shows how long to wait.

​
Handling

  • Watch X-RateLimit-Remaining and slow down as it approaches zero.
  • After a 429, wait Retry-After seconds and retry only the rejected request.
  • Do not blindly retry write requests after a network failure: first check whether the request was applied.
  • Cache responses that rarely change.
Cloudflare sits in front of the API and has its own limits. If one IP sends too many requests, Cloudflare itself responds with error 1015 (HTTP 429): its own page, not API JSON, and without X-RateLimit-* headers. Slow down and wait a few minutes: retrying during the block extends it.