Plans, usage, and limits.

Included usage

Each plan carries a monthly pool of included usage, measured in dollars. Every request draws from that pool according to the modelyou asked for and the tokens it used — heavier models draw faster, so the same pool goes much further on the workhorse tier than on a flagship. One meter, no per-model gates — every model on a paid plan, the open-model lineup on Free. On models that price cached input, repeated context draws less: it counts at that model's published cached rate. Where a model publishes no cached rate, repeated context counts at the ordinary input rate — we don't discount what the model doesn't — see Prompt caching.

Free is a one-time $2 credit granted when you sign up — it is not renewed each month. When it runs out, either load credit and keep going pay-as-you-go, or move to a subscription tier for a pool that does refresh monthly.

On a subscription tier the pool refreshes at the start of each monthly cycle. As it runs low, the heaviest models pace to your plan while everything else keeps full speed. The pool is also a hard cap: once it is used up, requests return 429 allowance_exhausted until the cycle resets — your plan never bills or serves past the usage it includes. Upgrading lifts it immediately.

Prepaid credit behaves differently, and your client should treat it differently: an empty balance returns 429 credits_exhausted with no Retry-After, because there is no reset date to wait for — only a top-up clears it. Branch on the two codes rather than retrying both.

Rate limits

Two published limits per plan: sustained requests per minute and concurrent requests (simultaneous in-flight calls, the axis that matters for parallel agent fleets).

Hitting a limit: 429 + retry-after

Past a limit, the API returns 429 with a retry-after header — the number of seconds to wait before retrying. The same status covers both cases:

• Rate limit— you sent requests faster than your plan's per-minute rate or held too many open at once. retry-after is typically a few seconds.
• Monthly cap — an account ceiling for the month was reached. retry-after points at the next monthly cycle; upgrading clears it immediately.

HTTP/1.1 429 Too Many Requests
retry-after: 12

{ "error": { "type": "rate_limit_error", "message": "..." } }

Honor retry-after exactly and add exponential backoff with jitter for repeated hits — the full recipe is on Errors. Current-window state is also reported on every response via the x-ratelimit-* headers — see Headers.

Need more?

Enterprise plans carry custom usage pools, higher limits (10,000+ requests/min, 250+ concurrent), and procurement-friendly billing.