Limite și prețuri

codai facturează per task reușit verificat, nu per token — comparația planurilor este pe codai.ro/pricing, iar cheltuiala ta live e în hub.codai.ro. Pagina asta acoperă ce aplică gateway-ul la fiecare cerere și cum îți spune când ai lovit un zid.

Rate limits

Limitele sunt per utilizator, peste toate cheile acelui utilizator, cu fereastră glisantă. Fiecare răspuns poartă starea curentă:

x-ratelimit-limit-minute: 120
x-ratelimit-remaining-minute: 117
x-ratelimit-reset-minute: 1790000060
x-ratelimit-limit-hour: 3000
x-ratelimit-remaining-hour: 2951
x-ratelimit-reset-hour: 1790003600

Valorile reset sunt timestamp-uri Unix în secunde. Limitele numerice vin din planul tău; le citești din header-e în loc să le hardcodezi.

Se aplică trei ferestre:

Pentru că citirile din cache sunt gratuite în fereastra de tokeni, a ține prompt caching pornit este și felul în care rămâi sub limită în sesiuni lungi de agent.

Respectă Retry-After

La fiecare 429 gateway-ul setează Retry-After la numărul exact de secunde până când cea mai veche intrare iese din fereastră — nu un 60 fix. Clienții care îl respectă găsesc un loc liber la prima reîncercare; clienții care îl ignoră bombardează gateway-ul și rămân blocați. SDK-urile reîncearcă 429 și 5xx cu backoff automat.

Plafoane de task-uri

Un task începe la o tură proaspătă de utilizator; continuările cu rezultat de tool și follow-up-urile din aceeași conversație nu pornesc altele noi. Planurile includ un număr de task-uri pe zi (sau pe lună la tier-ul gratuit). Când le epuizezi:

• Gateway-ul returnează 429 cu codul quota_exceeded și un Retry-After care indică resetarea.
• Conversațiile pe care le-ai pornit deja continuă să funcționeze — doar task-urile nou-nouțe sunt puse în pauză.
• Apelurile utilitare pe codai-fast cu X-Codai-No-Task: 1, embeddings, audio și realtime nu contează niciodată.

quota_exceeded este intenționat un 429, nu un 403: clienții IDE îl tratează ca „back off și reîncearcă mai târziu” în loc să reîncerce la fiecare câteva secunde.

Plafoane de cheltuieli

Conturile pot purta un plafon zilnic și unul lunar de cheltuieli în USD, însumat peste toate cheile. Când e activ, fiecare răspuns raportează unde te afli:

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

Depășirea unui plafon returnează 429 rate_limit_exceeded cu un mesaj care numește fereastra (plafoanele zilnice se resetează la miezul nopții UTC, cele lunare pe 1 UTC). Setezi bugete per cheie în hub la Keys — bugetul cheii e un prag sub plafonul contului, niciodată peste el.

Plafon per cerere

O singură cerere de nivel superior — inclusiv candidații best-of, apelurile de judecător și delegările către sub-agenți pe care gateway-ul le pornește pentru ea — se oprește devreme cu un răspuns parțial odată ce costul ei cumulat trece de 5 USD. Chat-ul simplu nu se apropie niciodată de el; există ca o buclă de agent scăpată de sub control să nu poată factura o sumă nelimitată într-un singur apel.

Dimensiunea body-ului

Body-urile cererilor pe /v1/* sunt limitate la 12 MB. Body-urile mai mari primesc 413 cu codul payload_too_large. Încărcările audio sunt limitate separat la 25 MB pe /v1/audio/transcriptions.

Chitanța de cost

Fiecare răspuns de chat sau messages poartă costul acelei cereri când poate fi cunoscut înaintea primului byte:

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

Micro-USD sunt numere întregi — 18420 înseamnă 0,01842 $. Pe stream-urile native numărul nu e cunoscut la momentul header-elor, așa că primești în loc x-codai-cost-estimate: pending, iar cifra exactă ajunge în endpoint-ul de chitanță:

# ultimele 24 de ore (implicit)
curl https://ai.codai.ro/v1/receipt -H "Authorization: Bearer $CODAI_API_KEY"

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

# de la un 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", "events": 130, "cost_micro_usd": 1801000 },
    { "upstream_model": "claude-haiku-4-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 este numărul de porniri de task facturabile din fereastră. session_id se potrivește fie cu X-Codai-Session-Id pe care l-ai trimis, fie cu cheia derivată de gateway pentru clienții fără header. Numărul de tokeni sunt cifrele reale de la upstream — parsate din message_delta.usage pe stream-urile Anthropic și din chunk-ul final de usage pe stream-urile OpenAI — nu numărul afișat de un client.

Prețurile per model upstream sunt afișate în hub lângă fiecare rând de usage; gateway-ul nu are un endpoint separat de prețuri.

Contractul de erori

Erorile folosesc anvelopa OpenAI pe fiecare suprafață, așa că un client OpenAI-compatibil le parsează neschimbat:

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

code este stabil și citibil de mașină; message este pentru oameni și se poate schimba. Eșecurile de validare adaugă un obiect details cu căile câmpurilor care au picat. Numele providerilor upstream sunt curățate din mesaje — vezi ce a picat, niciodată care cloud a servit.

Eșecurile din mijlocul unui stream nu pot schimba codul de status (header-ele au fost deja trimise); gateway-ul închide stream-ul cu un frame de stop curat și înregistrează tura ca blocată. Reîncerci cererea — prompt caching o face ieftină.

Ce se înregistrează la eșec

Cererile eșuate sunt înregistrate și ele, cu codul de eroare și is_task_start = 0 — o încercare eșuată nu facturează niciodată un task, iar orice consum de task rezervat înainte de dispatch este rambursat.