Rate and spend limits

Keiro rate limits are Keiro account limits. They are calculated for the public eb1 model you request. Public limits describe customer-visible capacity, not private serving architecture or vendor economics.

On this page 1 of 13

Paid beta accounts can have request, token, concurrency, model-access, and spend limits. Limits are account-specific and may change during the beta. The console and the response headers on API calls are the source of truth for your current effective limits.

When a rate limit is exceeded, the API returns HTTP 429. Retriable denials carry a Retry-After header; wait at least that many seconds before retrying. Denials that cannot succeed on retry say so instead — see Deterministic denials.

Limit surfaces

Use this matrix to decide whether to retry, queue, change model access, or contact support. Exact numeric limits stay account-scoped.

Limit surface Customer-visible state Client action
Controls Where to check
Request rate Request admission by minute or day. Response headers and console. Honor Retry-After; back off before retrying.
Token rate Input, output, and total token throughput. Response headers and console. Shorten prompts, reduce output, or queue work.
Concurrency How many requests can run at once. Response headers and console. Limit client-side parallelism per org and key.
Model access Which public eb1 models a key can use. /v1/models and console policy. Use only returned public model IDs.
Spend exposure Account and key spend controls. Console and support agreement. Contact support for limit changes during paid beta.
Streaming Whether streaming is enabled for the key and account. Console policy and request result. Fall back to non-streaming when access is unavailable.

How limits work#

A request is admitted only when every applicable limit allows it. The main limit dimensions are:

  • requests per minute or day
  • tokens per minute or day
  • input tokens per minute or day
  • output tokens per minute or day
  • concurrent requests
  • maximum context and output size
  • monthly or daily spend
  • maximum estimated exposure for a single request
  • model access and streaming access

Keiro may enforce input-token and output-token buckets separately for eb1 models. When those buckets are present, they are Keiro account buckets for the public eb1 request, not upstream provider limits.

For single-call requests, shared upstream capacity does not count cache reads where the serving quota exempts them. Warm admission uses the same tracked namespace as your input limit; a cache miss or failed call restores the assumed credit. Multi-call requests count the full prompt. Combined token quotas count the full prompt, including cached tokens, plus output.

Input tokens a request reads from the prompt cache, reported as cached_tokens in its usage, do not count toward the input-token bucket. Admission reserves the estimated uncached input when a tracked session has a warm prefix for the selected model and cache namespace. Without that evidence, it reserves the whole estimated prompt. Completion refunds unused reservations and charges any shortfall in the assumed cache reads to the input bucket; that charge can delay subsequent requests.

Account plans#

Your org plan defines the outer limits for:

  • allowed models
  • requests per minute or day
  • input and output tokens per minute or day
  • concurrent requests
  • maximum context and output size
  • monthly spend
  • maximum estimated exposure for a single request
  • whether streaming is enabled
  • how many API keys can be active

Invite-only paid beta plans remain separate from self-serve usage tiers. Those invite-only plans are named by account type rather than numbered usage tiers; see Invite plans.

Self-serve usage tiers use the Free plus Tier 1-5 model in Self-serve usage tiers, and numbered usage tiers are advanced from settled paid billing history. Some higher tiers may require capacity review before activation. The self-serve defaults are static account defaults for eb1-preview; the console and headers remain authoritative for your account's current effective limits.

Self-serve usage tiers are not open during the invite-only beta; the Self-serve usage tiers table shows the defaults that will apply when signup opens. To use the API today, request access.

Invite plans#

A beta organization starts with these limits for each public model:

ModelRequests/minTokens/minInput tokens/minOutput tokens/minConcurrent requests
eb1-preview3,0004,000,0003,000,000400,00050
eb1-frontier-preview3,0004,000,0004,000,000400,00050
eb1-fast-preview6002,500,0002,500,000400,00050
eb1-efficient-preview3,0004,000,0003,000,000400,00050

Beta spend caps apply to the whole organization:

Daily spend capMonthly spend capPer-request spend cap
None$5,000$240

Benchmark and Enterprise plans are set per organization; see the console. The console Limits page and the x-ratelimit-* response headers are authoritative for your requests, and per-model limits follow platform capacity, so they can change. To change a limit, contact support.

Self-serve usage tiers#

The current default self-serve limits for eb1-preview are:

Usage tierAdvancement basisMonthly spend limitActivationRequests/minTokens/minInput tokens/minOutput tokens/minConcurrent requests
FreeSignup eligibility$0Automatic520,00020,0004,0001
Tier 1$5 settled paid billing history$100Automatic60100,000100,00030,0005
Tier 2$50 settled paid billing history$500Automatic120200,000200,00060,00010
Tier 3$100 settled paid billing history$1,000Automatic240300,000300,000120,00020
Tier 4$250 settled paid billing history$5,000Capacity review500400,000400,000250,00050
Tier 5$1,000 settled paid billing historyCustomManual review1,000400,000400,000400,000100

Key overrides#

Individual API keys may have narrower limits than the org plan. A key cannot raise the limits of the org it belongs to. A key's own rate limit is checked against your organization's usage, so requests from every key in the organization count toward it.

If a key has no explicit override, it inherits the org plan. If a key is limited to specific models, model listing and request admission only show and allow the models that key can use.

Response headers#

Responses produced by the gateway include rate-limit headers describing the effective limits that applied to the call. Header names are case-insensitive; HTTP/2 and HTTP/3 deliver them lowercase on the wire, so match names case-insensitively.

Every API format carries the same headers, streaming or not: Chat Completions, Responses and Messages. Messages responses carry no other rate-limit header family, so a client that paces itself from rate-limit headers reads these names on every format.

HeaderMeaning
x-ratelimit-limit-requestsRequests-per-minute limit applied to this request.
x-ratelimit-remaining-requestsRequests remaining in the current window.
x-ratelimit-reset-requestsTime until the request allowance is fully restored.
x-ratelimit-limit-tokensCombined tokens-per-minute limit applied to this request.
x-ratelimit-remaining-tokensCombined tokens remaining in the current window.
x-ratelimit-reset-tokensTime until the combined token allowance is fully restored.
x-ratelimit-limit-input-tokensInput tokens-per-minute limit applied to this request.
x-ratelimit-remaining-input-tokensInput tokens remaining in the current window.
x-ratelimit-reset-input-tokensTime until the input token allowance is fully restored.
x-ratelimit-limit-output-tokensOutput tokens-per-minute limit applied to this request.
x-ratelimit-remaining-output-tokensOutput tokens remaining in the current window.
x-ratelimit-reset-output-tokensTime until the output token allowance is fully restored.
x-ratelimit-limit-concurrencyConcurrent-request limit applied to this request.
x-ratelimit-remaining-concurrencyConcurrent request slots currently available.
x-ratelimit-limit-spendBinding configured spend cap in USD; present only when a cap is configured.
x-ratelimit-remaining-spendRemaining headroom under that cap in USD (up to six decimals).
x-ratelimit-scopeorg when your account limits bind; platform when platform load is temporarily compressing them.
retry-after-msMilliseconds to wait before retrying; present alongside Retry-After on retriable denials and carries fractional precision.
x-should-retryfalse when an unchanged retry cannot succeed (deterministic denials); official SDKs honor it and stop auto-retrying.

x-ratelimit-reset-* values are durations such as 250ms or 56s. A dimension that is unlimited for your account emits no headers, and a fully unlimited request emits no x-ratelimit-* headers at all. When one of your account limits denies a request with 429, the response carries the headers named for the denied dimension and adds x-ratelimit-scope: a request-limit denial uses the -requests headers, an input- or output-token-limit denial uses the -input-tokens or -output-tokens headers (token limits are enforced per channel, so a denial never uses the combined -tokens names), a concurrency denial uses the -concurrency headers, and a spend-cap denial uses x-ratelimit-limit-spend. A per-request token-budget denial carries no token headers; its configured budget is in error.details.limit (dimension token_budget). A value the gateway does not know at denial time is omitted, never guessed. Two other 429 classes are the exception: a shared-capacity denial (capacity_exceeded) and a 429 passed through from an upstream provider carry no x-ratelimit-* headers, not even x-ratelimit-scope -- only the retry signals (Retry-After and retry-after-ms when retriable, x-should-retry: false on the insufficient_quota echo). Tell those apart by the error body, not by the presence of rate-limit headers: a shared-capacity denial has code capacity_exceeded, and an upstream 429 has no details.dimension.

A requests-per-minute, tokens-per-minute or concurrency 429 names whose limit it was: your organization's, or the API key's own (details.binding_scope is api_key when the key's limit bound). Requests from every key in your organization count toward a key's own limit. Platform load, shared capacity and an upstream 429 say they are not a limit on your organization or API key.

These standing headers are promised on gateway-origin responses only: responses produced by the gateway itself, whether success or error. Responses generated at the network edge (for example a 502 returned while the gateway is restarting) may carry none of them.

Treat these as operational hints for the current request and account. Do not build client logic that assumes a public eb1 model is backed by a specific serving implementation.

Retry-After#

Retriable rate-limited (429) responses on authenticated API requests, and 503 and 504 responses from the gateway, carry a Retry-After header with a whole number of seconds (minimum 1). Wait at least that long before retrying; a client that always honors Retry-After never compounds an overload. Retriable denials also carry retry-after-ms, the same horizon in milliseconds with fractional precision; prefer it when both are present.

The advertised horizon varies per request, so clients refused together do not retry together. Each request's value is the computed horizon below lengthened by up to a quarter, and by at most 30 seconds; it is never shorter than the computed horizon, and a computed horizon of 60 seconds or less is never lengthened past 60 seconds, the longest value the OpenAI and Anthropic SDKs honor. retry-after-ms carries that value, as do error.details.retry_after_seconds and a stream error frame's retry_after_seconds when present. Retry-After is the value rounded up to a whole second, so on short horizons it shows no spread: a 1-second horizon reads as Retry-After: 2 on almost every request.

How the computed horizon is set depends on the failure class:

  • Request and token limits: computed from the limiter's refill state, so it reflects when enough capacity for the denied request returns, including repayment of any outstanding usage settled after earlier requests.
  • Concurrency limits: a short interval sized to how quickly a slot frees up, less any time the request already waited for one.
  • Daily and monthly spend caps held by running requests: 5 seconds. Each running request holds its conservative cost estimate against the cap until it finishes and is charged its actual cost, which frees the rest.
  • Shared capacity and platform load: when shared capacity is expected to recover.
  • 503 and 504 responses: a short per-class default, or the upstream-provided value when one exists. A 503 for a temporarily unavailable platform dependency advertises 5 to 15 seconds, and one for a request that timed out waiting for serving capacity uses at least the time it already waited. A 502 carries Retry-After only when the upstream supplied one, and an upstream_auth_error never carries it.

Deterministic denials#

Some denials cannot succeed on retry because the request itself exceeds a cap that never self-clears: its token estimate is larger than a full minute of your token budget, it exceeds a per-request token budget, or its estimated cost exceeds a per-request spend cap. A spend cap set to $0.00 behaves the same way — no amount of waiting helps.

A daily or monthly spend cap refuses a request for one of three reasons, and only the money already spent decides whether the refusal is final:

  • Your spend has reached the cap. The refusal is final until the cap's UTC period ends: the start of the next UTC day for a daily cap, the first day of the next month (UTC) for a monthly cap.
  • What is left under the cap is less than this request's estimated cost. The same request is refused until the period ends, so this is final too; a request with a lower max_output_tokens holds less and may fit now.
  • Requests already running hold the rest of the cap. This one is retriable: see Retry-After.

A final refusal carries x-should-retry: false, "retryable": false, and no Retry-After or retry-after-ms header, because the reset can be hours or days away, longer than any client should wait. error.details.resets_at gives the reset as an RFC 3339 UTC timestamp, and the message names it. To raise your organization's cap, contact support (see Spend exposure). A cap set on an API key when it was created is checked against your organization's spend in the period, not that key's alone: the message names the key's cap, and a key with a higher cap, or support, is the way past it. When both a daily and a monthly cap refuse, a final monthly refusal is named first, since the month resets last and resets_at is then when the request can next succeed; otherwise a final daily refusal, and a cap held by running requests only when neither is final.

A request whose token estimate exceeds a full minute of your token budget is rejected as a 400 invalid_request_error with code request_exceeds_capacity and no retry header of any kind: it is a request problem, not a rate problem. Reduce the input or the output token limit (max_tokens, or max_output_tokens on Responses), or raise the limit, and resend.

The remaining deterministic denials (per-request token budget, per-request spend cap, $0.00 cap, and the final daily or monthly cap refusals above) stay 429 and carry x-should-retry: false and "retryable": false in the error body, and no Retry-After or retry-after-ms header; their message says what was measured and which knob to change. OpenAI-compatible SDKs honor x-should-retry and stop auto-retrying these responses without any client change.

Where limits are disclosed#

Limits are visible on three surfaces:

  • Response headers: the effective per-request values after any temporary compression (for example platform load). Authoritative for what your next request can do right now.
  • GET /v1/models: the configured static limits for your account and model.
  • The console and the tier table above: configured static defaults.

When surfaces disagree, the response headers win for the current moment; the configured values describe your steady-state entitlement.

Token accounting#

Keiro bills and reports usage from canonical Keiro token accounting. For eb1 variants, the public model you request is the billing unit; the usage summary does not expose private serving architecture, non-public vendor data, or internal serving choices.

For each completed request, finalized usage is assembled from normalized Keiro request and response usage:

  • input tokens
  • output tokens
  • reasoning tokens when a model reports them
  • the public model or eb1 variant
  • the active price-book version
  • the billing mode for your account

Provider-reported token counts can be used as evidence for reconciliation, but customer-visible usage and spend are based on the finalized Keiro usage record. If a paid non-BYOK request cannot be priced, it fails before provider dispatch instead of silently billing at zero.

Spend exposure#

Spend checks happen before dispatch using conservative estimates. They are not an exact reservation of future output tokens: streaming and reasoning output are known only after completion. After the request finishes, finalized canonical usage settles the spend record.

An ultra request holds more of your limit while it runs, because it can spend its whole output limit reasoning. It is therefore refused near a limit where a normal request would pass. A lower output limit holds less.

If an org or key spend limit is exceeded, the API returns HTTP 429 with code rate_limit_exceeded. The message names the cap and the next step (see Deterministic denials); the error omits private billing details and sensitive operational context.

Run a Python request Python
from getpass import getpass

from openai import OpenAI

# The SDK already retries 429 and 5xx responses with jittered exponential
# backoff and honors Retry-After; max_retries is the only knob most
# applications need.
client = OpenAI(
    base_url="https://api.keirolabs.ai/v1",
    api_key=getpass("Keiro API key: "),
    max_retries=5,
)

response = client.chat.completions.create(
    model="eb1-efficient-preview",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

print(response.choices[0].message.content)

Use client.with_options(max_retries=0) on a call when you would rather fail fast than wait out a backoff. To observe the horizon yourself, catch openai.RateLimitError and read exc.response.headers.get("retry-after"); a deterministic denial carries none.

Owners, admins and billing members of your organization get an email when settled spend first reaches 75% of a daily or monthly spend cap in a UTC period, and another when that cap first refuses a request in the period.

Spend-limit changes are handled through support during paid beta. Do not share API keys in support tickets.

Search Keiro docs

Start typing to search pages and sections.

Start typing to search pages and sections.

Documentation

Console