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, and 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"
  }
}