API rate limits
Every request to /api and /mcp counts against a budget. Signed-in requests
count against your account; anonymous requests count against your network
address. This page lists the limits, how to read them and what to do when you
hit one.
Limits
| Policy | Applies to | Limit |
|---|---|---|
api | Every signed-in API request and every signed-in MCP request | 1,000 per 60 s, times your plan multiplier |
api-heavy | Expensive requests (compare, blame, code search, archives, pull request diffs), on top of api | 120 per 60 s signed in, times your plan; 10 anonymous |
api-anon | Every anonymous API and MCP request | 1,200 per hour per address |
feedback | Sending feedback through the API, on top of api | 20 per day |
web | Every web page load | 3,600 per hour per address |
- Every credential of one account (browser session, personal access token, OAuth token, CLI login) shares one count.
- Anonymous requests are counted per IPv4 address or per IPv6 /64 network.
- Password Basic authentication uses the anonymous address budgets, including the reduced heavy-request limit, before password verification. It does not receive a per-account or plan-multiplied budget. A grant token sent as a Basic password uses the token budget instead.
- Git clone, fetch and push, and Git LFS, are not rate limited.
The API reference marks each limited operation with its
policies in x-gc2-ratelimit.
Plan multipliers
The api and api-heavy limits are multiplied by the highest
plan among your personal account and the
organizations you are a member of. Outside collaborators do not get an
organization's plan. Anonymous, feedback and web limits are never multiplied.
| Plan | Multiplier |
|---|---|
| Free | 1× |
| Pro | 2× |
| Team Standard | 5× |
| Team Premium | 10× |
| Enterprise | 20× |
A plan or membership change takes effect within about 11 minutes.
Read your limit
Successful responses carry the policies that were checked, with the quota q
and the window w in seconds:
| 1 | RateLimit-Policy: "api";q=2000;w=60 |
The API does not report how many requests remain.
Handle a 429
A request over its budget is refused with 429 Too Many Requests:
| 1 | HTTP/1.1 429 Too Many Requests |
| 2 | Retry-After: 17 |
| 3 | RateLimit: "api-heavy";r=0;t=17 |
| 4 | RateLimit-Policy: "api";q=1000;w=60, "api-heavy";q=120;w=60 |
| 5 | Content-Type: application/problem+json |
| 6 | |
| 7 | { |
| 8 | "type": "https://cafe.sh/errors/rate-limit-exceeded", |
| 9 | "title": "Rate limit exceeded", |
| 10 | "status": 429, |
| 11 | "detail": "The api-heavy limit allows 120 requests per minute.", |
| 12 | "policy": "api-heavy", |
| 13 | "limit": 120, |
| 14 | "window_seconds": 60, |
| 15 | "retry_after_seconds": 17 |
| 16 | } |
- Wait at least
Retry-Afterseconds before retrying. - If the retry is limited too, back off further: limits use a sliding window, so a caller far over its budget can need more than one window to recover. An hourly or daily budget recovers gradually through the next hour or day.
- Spread bulk work over time, sign in to get a per-account budget, or upgrade your plan for a higher multiplier.