Rate limits

Recover from transient request-rate limits without confusing them with quota or budget exhaustion.

Rate limits control request pace for one API key, whether a project key or a company-level key. A company-level key has one window for every project it serves. They are separate from monthly usage quotas, hard budgets, credits, and billed capability work.

Every request that successfully authenticates to /v1 consumes one place in that key's rolling 60-second window. This includes reads, polling, validation failures, idempotent replays, and calls to Usage. Missing, invalid, revoked, and expired credentials do not enter a key's window because no key can be identified.

The limit per 60 seconds comes from your organization's usage tier (see Usage tiers); 120 requests per 60 seconds applies only when a deployment has no usage tiers. Use the policy and live window values returned by the API:

Response valueMeaning
RateLimit-LimitRequests allowed in the current 60-second window.
RateLimit-RemainingRequests still available after the current request.
RateLimit-ResetWhole seconds until the oldest request leaves the current window.
Retry-AfterOn rate_limit_exceeded only, the minimum whole seconds to wait before retrying.

The three RateLimit-* headers appear on authenticated success and error responses. GET /v1/usage also returns rate_limit.limit and rate_limit.window_seconds for policy discovery.

The per-minute limit is set by the organization's usage tier, which advances automatically with cumulative credit purchases and account age. GET /v1/usage returns the current tier as usage_tier (key, name, rank, rate_limit_per_minute, monthly_cost_cap_usd). Each tier also carries a monthly spend cap, counted in what the organization is charged during the UTC calendar month (monthly_cost_cap_usd is the cap that applies: the tier's, or the organization's lifetime gifted credit when that is higher): when it is reached, job creation fails 429 budget_exceeded with error.details.scope of "usage_tier" — like budget exhaustion, this is not transient and resets at error.details.resets_at. The refusal's details also carry tier (the tier key), limit_usd (the cap that applies), spend_usd (charged this month), and reserved_usd.

Usage tiers#

Organizations move up the tier ladder automatically as they build history — no request or review is needed. Advancement is based on two signals: lifetime credit purchases (settled payments; promotional credits never advance the tier) and days since your first payment. Both thresholds must be met.

The ladder:

TierQualificationRequests/minMonthly spend cap
FreeNew organization60$100
Tier 1$50 purchased120$500
Tier 2$500 purchased, 7+ days300$2,500
Tier 3$2,500 purchased, 14+ days600$10,000
Tier 4$10,000 purchased, 30+ days1,200No monthly cap

Two adjustments can apply to an individual organization:

  • Promotional credits raise the cap. An organization granted promotional credit can always consume it: the effective monthly cap never sits below the total promotional credit granted, even on the Free tier.
  • Support can pin a tier. Limits set by support override the computed tier in both directions and are shown on the Limits page.

On a tier with a monthly spend cap, your organization runs one job at a time, across all of its projects and keys. A job holds the rest of the month's cap from the moment it is accepted until it finishes, because its price isn't known until then. Another job submitted meanwhile is refused with 429 budget_exceeded, details.scope of "usage_tier", a reserved_usd above zero and a spend_usd below limit_usd: submit it again when the first job finishes. Tier 4, which has no monthly spend cap, has no such limit: its jobs can run at the same time.

Your current tier, effective monthly cap, and progress to the next tier are on the console Settings → Limits page. If you need higher limits than your tier allows, contact support.

When request pace is too high, the API returns 429 with error.code set to rate_limit_exceeded. Wait at least the larger of Retry-After and RateLimit-Reset, then retry with bounded exponential backoff and jitter. Polling consumes request-rate capacity but does not create or bill another generation run.

quota_exceeded and budget_exceeded also return 429, but neither is a transient request-rate failure and neither carries Retry-After. Use error.details.resets_at and the counters in Limits, budgets, and usage to decide whether to wait for the next UTC month or ask an administrator to change the control. The complete decision table is in Errors.