Rate limits & quotas

The default envelopes

Unless an administrator has set otherwise on your key, the limits are 5 requests per second, 60 per minute, 5,000 per day, and 100,000 per month. Windows are fixed, not sliding, and reset independently. /v1/me reports the envelopes actually in force on your key together with live usage — read it rather than assuming either the defaults or the figures in any example.

The narrowest window is charged first, and a wider one is only charged once every narrower one has passed — so a client looping against the per-second limit cannot spend its daily budget on rejections.

Response headers

Six X-RateLimit-* headers ride on every successful authenticated response and on rate_limit_* and quota_exceeded rejections — nowhere else. There is no X-RateLimit-Reset: use Retry-After on a 429, which points at the real window edge. The monthly quota has no header at all; read it from /v1/me. When the limiter's own store is unavailable the service fails open and omits the headers rather than reporting an allowance it cannot confirm.

X-RateLimit-Limit-Second: 5
X-RateLimit-Remaining-Second: 4
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Limit-Day: 5000
X-RateLimit-Remaining-Day: 4997

The unsuffixed X-RateLimit-Limit and X-RateLimit-Remaining are the minute window.

When a limit is exceeded

Exceeding an envelope returns 429 with a Retry-After value in seconds and one of: rate_limit_second, rate_limit_minute, rate_limit_day, or quota_exceeded. All four carry Retry-After — pointing at the next second, minute, midnight or month boundary respectively — alongside the live X-RateLimit-* headers. Wait for the period it gives rather than guessing a back-off.

{
  "error": {
    "code": "rate_limit_minute",
    "message": "Rate limit exceeded: 60 requests per minute.",
    "details": { "limit": 60, "window": "minute" },
    "request_id": "req_7f3a2c"
  }
}