Rate limits & headers ​

Rate limits are applied per organization, across all of your keys and the MCP server together — not per key.

The limit ​

The limiter is a token bucket that holds 60 tokens and refills at 1 token per second. In practice:

  • You can burst up to 60 requests back-to-back.
  • Sustained throughput settles at about 1 request per second as the bucket refills.

Headers ​

Every response includes the current state of your window:

HeaderMeaning
X-RateLimit-LimitBucket size (the ceiling)
X-RateLimit-RemainingTokens left right now
X-RateLimit-ResetUnix time (seconds) when the bucket is full again

Read X-RateLimit-Remaining and back off before you hit zero rather than waiting for a 429.

When you're limited ​

Exceeding the limit returns 429 RATE_LIMIT_EXCEEDED in the unified error shape, plus a Retry-After header giving the number of seconds to wait:

http
HTTP/1.1 429 Too Many Requests
Retry-After: 3
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000003
json
{
  "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded" },
  "request_id": "req_..."
}

Honor Retry-After: sleep for that many seconds, then retry. Exponential backoff on repeated 429s is a good default for automated clients.

Rate limits vs credits

Rate limits cap how fast you call; credits cap how much you call. They're independent — you can have credits left and still be rate-limited, or be well under the rate limit and out of credits.