Întrebări frecvente despre gateway
Răspunsuri rapide — erorile 401, 402 și 429, ce model a servit o cerere, plafoanele de cheltuieli și rambursările.
Răspunsuri scurte la întrebările pe care le primește cel mai des suportul. Fiecare trimite la pagina cu toate detaliile.
De ce primesc 401 invalid_api_key?
Cheia lipsește, e greșită sau nu mai e validă. message îți spune care dintre ele:
message | Ce faci |
|---|---|
Missing or invalid API key | Nu a ajuns la gateway niciun header Authorization: Bearer codai_…. Verifică numele header-ului și că clientul îl trimite la fiecare cerere. |
Invalid API key | Cheia nu există. Copiaz-o din nou din hub.codai.ro → Chei — o cheie se afișează întreagă o singură dată, la creare. |
API key is disabled | Cheia a fost revocată sau dezactivată în hub. Creează una nouă. |
API key was rotated and its grace period has ended | Folosește cheia nouă rezultată din rotire. |
API key is paused until … | Cheia e pusă pe pauză până la acel moment. |
API key has expired / API key expired after a period of inactivity; sign in again | Creează o cheie nouă sau autentifică-te din nou în aplicația care a emis-o. |
Verifică și URL-ul de bază: este https://ai.codai.ro/v1. O cale greșită returnează 404 not_found, nu 401. Și https://ai.codai.ro/ deschis în browser răspunde 404: este un API, nu o pagină web — panoul de control este hub.codai.ro, iar documentația aceasta este locul de pornire.
De ce primesc 402?
402 înseamnă „pentru asta e nevoie de bani sau de un plan pe care nu îl ai acum”. code îți spune care e situația:
code | Unde | Ce faci |
|---|---|---|
subscription_inactive | Orice cerere, când cheia aparține unui abonament inactiv. | Reînnoiește sau schimbă planul în hub, la Facturare. |
insufficient_balance | La pornirea unui mediu administrat (portofelul trebuie să acopere o oră) sau la folosirea sandbox-urilor cu utilizare de sandbox neplătită. | Alimentează portofelul în hub; corpul răspunsului conține sumele. |
insufficient_funds | La acceptarea unei oferte Resolve cu sold prea mic. | Corpul are un topup_url pentru exact suma lipsă. |
Epuizarea task-urilor din plan nu este 402 — este 429 quota_exceeded (mai jos).
De ce primesc 429?
Două limite diferite folosesc același cod de stare. Le deosebești după error.code:
rate_limit_exceeded— încetinește. Fie fereastra de cereri pe minut / pe oră sau cea de tokeni de input / output e plină, fie ai atins plafonul de cheltuieli zilnic sau lunar.Retry-Aftereste numărul exact de secunde de așteptat.quota_exceeded— alocarea de task-uri a planului e consumată și nimic altceva (portofel, credite preplătite, depășire) nu plătește un task nou. Conversațiile deja pornite continuă; doar task-urile noi așteaptă.Retry-Afterindică resetarea (luna UTC următoare sau 00:00 UTC pentru un plafon zilnic).
Ambele au type: "rate_limit_error", deci un SDK OpenAI aruncă RateLimitError pentru amândouă. Detalii în limite și prețuri și task-uri și cheltuieli.
Ce model a servit efectiv cererea mea?
Apelezi întotdeauna codai; gateway-ul alege modelul upstream. Fiecare răspuns de chat, messages și audio spune care a fost, în header-ele de răspuns:
| Header | Semnificație |
|---|---|
x-codai-routed-to | Modelul upstream concret care a servit cererea. |
x-codai-provider | Adaptorul de furnizor, de ex. vertex-anthropic. |
x-codai-generator | codai/<model upstream>, trimis împreună cu x-codai-ai-generated: true la fiecare răspuns care conține output de model. |
curl -sD - -o /dev/null https://ai.codai.ro/v1/chat/completions \
-H "Authorization: Bearer $CODAI_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"codai","messages":[{"role":"user","content":"Hello"}]}' | grep -i x-codai-routed-toTotalurile per model pe un interval sunt în GET /v1/receipt (by_upstream). Toate header-ele: header-ele cererii.
Cum funcționează plafoanele de cheltuieli?
Poți seta un plafon zilnic și unul lunar în hub; se însumează peste toate cheile tale, iar bugetele per cheie stau sub el, niciodată peste. Cât timp plafoanele sunt active, fiecare răspuns are x-codai-spend-day-usd, x-codai-spend-day-cap-usd, x-codai-spend-month-usd și x-codai-spend-month-cap-usd. Când atingi un plafon, gateway-ul răspunde 429 rate_limit_exceeded, cu un mesaj care numește fereastra: plafoanele zilnice se resetează la miezul nopții UTC, cele lunare pe 1 ale lunii (UTC). Plafonul se compară cu costul upstream măsurat de gateway, exprimat în USD — de aici numele cu -usd. Mai multe în limite și prețuri.
Îmi primesc banii înapoi când ceva eșuează?
- O cerere eșuată nu costă nimic. Se înregistrează cu
is_task_start = 0, deci nu facturează niciodată un task, iar un credit preplătit sau un task contorizat rezervat înainte de trimitere se rambursează automat când upstream-ul nu a servit cererea. - Task-urile se facturează după rezultat. Task-urile din IDE, API sau CLI așteaptă confirmarea ta în hub, la Task-uri: Nu închide task-ul ca
failși nu se taxează nimic; un task neconfirmat în 24 de ore nu se facturează ca reușit. Pe planurile cu portofel, confirmarea Da rambursează costul de tokeni deja taxat în contul prețului fix de succes. Vezi task-uri și cheltuieli. - Resolve rambursează integral suma blocată când un job se încheie fără o reparație verificată (prețuri și limite).
- Utilizarea deja consumată nu se rambursează, pentru că modelul costă în momentul cererii. Consumatorii din UE se pot retrage dintr-o cumpărare de credit preplătit sau dintr-un abonament în 14 zile: partea nefolosită se rambursează, cea folosită nu. Folosește codai.ro/ro/withdrawal. Textul obligatoriu este în Termeni.
Unde găsesc ajutor?
Scrie-ne la [email protected] sau răspunde la orice email trimis de codai. Starea serviciului este live la codai.ro/status. Când raportezi o problemă, include x-codai-trace-id (sau propriul tău X-Request-Id) al unei cereri eșuate — așa găsim exact cererea fără să-ți vedem promptul.