API rate limits#

Every /api and /mcp request counts against a request budget: signed-in callers per account, anonymous callers per network address. This page explains how to read your limit, what a limited response looks like and how to recover.

Who is limited#

• Signed-in callers. A request authenticated with a browser session, a personal access token or an OAuth access token (REST or MCP) counts against the account that owns the credential, including a token sent as the password in HTTP Basic. Every credential of one account shares one count. A brand-new credential counts on its own at the Free limit until its first successful request has been processed, usually within seconds.
• Anonymous callers. A request without credentials counts against its client address: an IPv4 address, or the IPv6 /64 network it belongs to.
• Not limited: HTTP Basic with an email and password, signed provider webhooks (Stripe, Buildkite), and the Actions runner control endpoints.
• Git transports (clone, fetch, push, LFS) are not covered by these limits yet.

Web pages count separately: each page load uses the web budget of the visitor's address, and the API reads a page makes while it renders do not use the anonymous API budget.

Policies#

The OpenAPI document marks each limited operation with x-gc2-ratelimit, naming its policies (for example {"policies": ["api", "api-heavy"]}), and a 429 response. The document-level x-gc2-ratelimit-policies gives each policy's limit and window for signed-in and anonymous callers.

Plan multipliers#

Signed-in limits are multiplied by the highest plan among your personal account and the organizations you belong to as a member (outside collaborators do not inherit an organization's plan). An app installation token uses its organization's plan. Anonymous and web limits are never multiplied.

A plan or membership change, or a revoked credential, reaches your limit within about 11 minutes.

Read your limit#

Successful limited responses carry the policies that were checked, with your quota q and window w in seconds:

Error responses other than 429 do not carry this header. The API does not report a remaining count.

Handle a 429#

A request over its budget returns 429 Too Many Requests before any work is done:

A limited web page returns the 429 page with the same Retry-After, RateLimit and RateLimit-Policy headers.

1. Wait at least Retry-After seconds before retrying.
2. If the retry is also limited, back off further. Retry-After is a hint: limits use a sliding window, so a caller far over its budget may need more than one window to recover.
3. Spread bulk work over time, sign in for a per-account budget, or upgrade the plan for a higher multiplier.

Each policy admits q requests per window. Counts are approximate across the fleet, so a caller may occasionally be admitted slightly over its quota. Do not rely on exact counts. If the rate-limit service itself is unavailable, requests are not limited rather than rejected.