Limits & pricing

codai bills per verified successful task, not per token — the plan comparison is on codai.ro/pricing and your live spend is in hub.codai.ro. This page covers what the gateway enforces on every request and how it tells you when you hit a wall.

Rate limitsCopy Anchor Link

Limits are sliding-window and come from your plan. Each key has its own window (keys minted by an app share one window per subscription). These are the plan values:

• Requests per hour is a backstop of 30 × the per-minute limit.
• Input tokens per minute is the default for every plan; a key can carry a lower limit set in the hub.
• Own MCP servers is how many MCP servers of your own you can connect; a dash means the plan does not include them.
• The table is generated from the same plan catalog as codai.ro/pricing and codai.ro/pricing.json.

Each response carries the current state. Example for a Builder key:

x-ratelimit-limit-minute: 100
x-ratelimit-remaining-minute: 97
x-ratelimit-reset-minute: 1790000060
x-ratelimit-limit-hour: 3000
x-ratelimit-remaining-hour: 2951
x-ratelimit-reset-hour: 1790003600

reset values are Unix timestamps in seconds. Read the limits from the headers rather than hard-coding them: a per-key limit set in the hub, or a plan change, takes effect without a client change.

Three windows are enforced:

Because cache reads are free for the token window, keeping prompt caching on is also how you stay under the limit in long agent sessions.

Honour Retry-AfterCopy Anchor Link

On every 429 the gateway sets Retry-After to the exact number of seconds until the oldest entry ages out of the window — not a flat 60. Clients that honour it find a free slot on the first retry; clients that ignore it hammer the gateway and stay blocked. The SDKs retry 429 and 5xx with backoff automatically.

Task capsCopy Anchor Link

A task starts on a fresh user turn; tool-result continuations and follow-ups inside the same conversation do not start new ones. Plans include a number of verified tasks per month:

Past the allowance, each verified task is billed as overage at €1.20, when your billing allows overage. The €1.20 covers up to €1.20 of model usage for that task; unusually large tasks (above €1.20 of model usage) are billed for the excess at standard token rates, never below 1.2× upstream cost. Details in tasks and spend. When nothing pays for a new task:

• The gateway returns 429 with code quota_exceeded and a Retry-After pointing at the reset.
• Conversations you already started keep working — only brand-new tasks are paused.
• Utility calls on codai-fast with X-Codai-No-Task: 1, embeddings, audio and realtime never count.

quota_exceeded is deliberately a 429, not a 403: IDE clients treat it as "back off and retry later" instead of retrying every few seconds.

Spend capsCopy Anchor Link

Accounts may carry a daily and a monthly spend cap, set in EUR in the hub and summed across all keys. The cap is a guardrail, not an invoice: the gateway compares it one-to-one with the upstream cost it measures, which is in USD — hence the -usd header names. When enabled, each response reports where you stand:

x-codai-spend-day-usd: 3.42
x-codai-spend-day-cap-usd: 20.00
x-codai-spend-month-usd: 41.90
x-codai-spend-month-cap-usd: 300.00

Crossing a cap returns 429 rate_limit_exceeded with a message naming the window (daily caps reset at midnight UTC, monthly on the 1st UTC). Set per-key budgets in the hub under Keys — the key's budget is a floor under the account cap, never above it.

ImagesCopy Anchor Link

Image generation and editing are billed from the token usage the model reports, at the Vertex rates of the model that served the call — output image tokens, input text and input/reference images. Approximate price of one 1K image with no reference images:

Higher image_size values and reference images cost more. The charge is reported in x-codai-cost-micro-usd, recorded in the receipt, and counts toward the daily and monthly spend caps like any other cost. On prepaid plans the EUR wallet is debited for images too, at that USD cost converted to EUR with a 1.3 service multiplier (≈ €0.083 for a default image). Image calls never start a task, so they do not use your task allowance. A request whose images are all blocked by the safety filter (content_filtered) costs nothing.

Per-request ceilingCopy Anchor Link

A single top-level request — including any best-of candidates, judge calls and sub-agent delegations the gateway spawns for it — aborts early with a partial answer once its running cost crosses 5 USD. Plain chat never gets near this; it exists so a runaway agent loop cannot bill an unbounded amount in one call.

Usage-policy checkCopy Anchor Link

Agent steps that may break the model providers' usage policies are reviewed before they are sent upstream. A step judged a false positive goes through unchanged. Otherwise the gateway does not return an error: the response is a normal 200 assistant message that tells the agent what legitimate context is missing (whose system, what authorisation, what defensive purpose) or which part to drop. After 3 consecutive flagged steps within 24 hours the message tells the agent to stop pursuing that goal, and further suspicious steps are declined the same way until the window expires; unrelated work is unaffected. These responses carry x-codai-policy (ambiguous, violating, refused, refused-remembered, or cleared for a reviewed false positive) and x-codai-policy-strikes, and cost nothing. Rewording a request to get around the check counts as another strike.

Body sizeCopy Anchor Link

Request bodies on /v1/* are capped at 12 MB. Larger bodies get 413 with code payload_too_large. Audio uploads are separately capped at 25 MB on /v1/audio/transcriptions.

Cost receiptCopy Anchor Link

Every chat or messages response carries the cost of that request when it can be known before the first byte:

x-codai-upstream: claude-opus-5-5
x-codai-cost-micro-usd: 18420

Micro-USD are integers — 18420 is $0.01842. On native streams the count is not known at header time, so you get x-codai-cost-estimate: pending instead and the exact figure lands in the receipt endpoint:

# last 24 hours (default)
curl https://ai.codai.ro/v1/receipt -H "Authorization: Bearer $CODAI_API_KEY"

# one session
curl "https://ai.codai.ro/v1/receipt?session_id=my-project" -H "Authorization: Bearer $CODAI_API_KEY"

# since a timestamp
curl "https://ai.codai.ro/v1/receipt?since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $CODAI_API_KEY"

{
  "events": 142,
  "tasks": 9,
  "cost_micro_usd_total": 1834200,
  "cost_usd": 1.8342,
  "prompt_tokens": 2210034,
  "completion_tokens": 41890,
  "cached_read_tokens": 1988001,
  "cache_write_tokens": 120433,
  "by_upstream": [
    { "upstream_model": "claude-opus-5-5", "events": 130, "cost_micro_usd": 1801000 },
    { "upstream_model": "claude-haiku-5-5", "events": 12, "cost_micro_usd": 33200 }
  ],
  "window": { "from": "2026-09-22T09:00:00.000Z", "to": "2026-09-23T09:00:00.000Z", "session_id": null }
}

tasks is the number of billable task starts in the window. session_id matches either the X-Codai-Session-Id you sent or the key the gateway derived for header-less clients. Token counts are the real upstream figures — parsed from message_delta.usage on Anthropic streams and from the final usage chunk on OpenAI streams — not the headline number a client might display.

Prices per upstream model are shown in the hub next to each usage row; the gateway has no separate pricing endpoint.

Error contractCopy Anchor Link

Errors use the OpenAI envelope on every surface, so an OpenAI-compatible client parses them unchanged:

{
  "error": {
    "message": "You're sending requests a little too fast — the limit is 100 requests per minute …",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

code is stable and machine-readable; message is for humans and may change. Validation failures add a details object with the field paths that failed. Upstream provider names are scrubbed from messages — you see what failed, never which cloud served it.

Mid-stream failures cannot change the status code (headers are already sent); the gateway closes the stream with a clean stop frame and records the turn as stalled. Retry the request — prompt caching makes it cheap.

What is recorded on failureCopy Anchor Link

Failed requests are recorded too, with the error code and is_task_start = 0 — a failed attempt never bills a task, and any task consumption reserved before dispatch is refunded.