Rate & spend limits

Every INFRO key is governed by two independent limits: a rate limit on requests per minute and an optional spend limit capping the dollars it can consume. Rate limits protect throughput; spend limits protect your budget. Both are enforced per key, so you can tune them per service in the console.

This page covers how each limit works, the headers that report your standing, and what the 429 and 402 failure modes look like. For the full error catalog and retry rules, see Errors.

Rate limits

Each key gets a requests-per-minute budget that starts at 200 RPM and grows automatically with your account balance — no request form, no approval. Every response reports the current ceiling in X-RateLimit-Limit, so read your live limit from there rather than assuming the base.

Token throughput is limited per model, not per key, and pooled across every provider serving that model. Because capacity aggregates across upstreams, tokens are rarely the bottleneck — the per-key RPM budget is almost always the limit you hit first. Provider failover consumes no extra budget: a request that reroutes internally still counts as one. See Routing for how providers are selected.

Rate limit headers

Every response — success or error — carries three headers describing the key's current window.

HTTP/2 200
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 173
X-RateLimit-Reset: 1755950520

Read X-RateLimit-Remaining in your client and throttle before it hits zero. Proactive throttling is cheaper than absorbing 429s and keeps latency predictable under load.

When you hit the rate limit

Exceeding the RPM budget returns 429 with type rate_limit_exceeded and a Retry-After header giving the seconds to wait.

HTTP/2 429
Retry-After: 12
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1755950532

{
  "error": {
    "message": "Rate limit exceeded: 200 requests per minute for this key.",
    "type": "rate_limit_exceeded",
    "code": null
  }
}

Honor Retry-After when present, and retry with exponential backoff plus jitter. 429 is one of the four retryable statuses, alongside 408, 502, and 503; never auto-retry 400, 401, 402, or 404. Reference retry implementations are in Errors.

Spend limits

A spend limit is a hard USD ceiling attached to a key, set when you create it in the console or edited later. Once the key's cumulative usage reaches the limit, every subsequent request fails with 402 insufficient_credits until you raise or reset it. The same 402 is returned when your account's credit balance runs out, regardless of per-key limits.

{
  "error": {
    "message": "Insufficient credits: this key has reached its spend limit.",
    "type": "insufficient_credits",
    "code": null
  }
}

For per-request accounting, every response includes usage.cost — the exact USD charged; see Chat completions. For a key's cumulative spend, query GET /v1/key.

Checking a key's usage

GET /v1/key returns the current key's label, spend limit, and usage so far. Poll it from dashboards or pre-flight checks to see where a key stands.

curl https://api.infro.io/v1/key \
  -H "Authorization: Bearer $INFRO_API_KEY"

{
  "label": "prod-checkout",
  "limit": 250.00,
  "usage": 187.42,
  "limit_remaining": 62.58
}

labelstring

The name assigned to the key in the console. Useful for confirming which key a service is actually using — see Authentication.

limitnumber | null

The key's spend ceiling in USD. null if no limit is set.

usagenumber

Cumulative USD spent by this key.

limit_remainingnumber | null

limit minus usage. null when the key has no spend limit.

Handling burst traffic

• Use one key per service. Each key has its own RPM budget and spend ceiling, so a spike in one service cannot starve another — and per-key labels make cost attribution trivial.
• Watch X-RateLimit-Remaining. Throttle client-side as it approaches zero instead of absorbing 429s; a token-bucket limiter fed by the header keeps tail latency flat.
• Respect Retry-After and add jitter. Synchronized retries from a fleet of workers re-trigger the limit in lockstep; randomized backoff breaks the herd.
• Consolidate small calls. The RPM budget counts requests, not tokens — a streamed response is still one request, so fewer, larger calls stretch the budget further.
• Top up to scale. RPM grows with account balance. If you consistently run near X-RateLimit-Limit, adding credits raises the ceiling without a support ticket.