# Rate limits

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

Canonical guide: <https://engine.neraperla.com/docs/rate-limits>

Raw Markdown: <https://engine.neraperla.com/docs/raw/rate-limits.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

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](#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 value | Meaning |
|---|---|
| `RateLimit-Limit` | Requests allowed in the current 60-second window. |
| `RateLimit-Remaining` | Requests still available after the current request. |
| `RateLimit-Reset` | Whole seconds until the oldest request leaves the current window. |
| `Retry-After` | On `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:

| Tier | Qualification | Requests/min | Monthly spend cap |
|---|---|---|---|
| Free | New organization | 60 | $100 |
| Tier 1 | $50 purchased | 120 | $500 |
| Tier 2 | $500 purchased, 7+ days | 300 | $2,500 |
| Tier 3 | $2,500 purchased, 14+ days | 600 | $10,000 |
| Tier 4 | $10,000 purchased, 30+ days | 1,200 | No 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](https://engine.neraperla.com/docs/usage-quotas) 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](https://engine.neraperla.com/docs/errors).
