Gestionează codurile publice de eroare din API-ul Rivya, stările HTTP, limitele de rată, conflictele de idempotentă și deciziile de reîncercare.

API-ul Rivya returnează coduri publice stabile de eroare în JSON. Tratează valoarea error.code drept parte a contractului de integrare.

Formă erorii

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

Păstrează requestId în jurnale atunci când ceri echipei de asistență Rivya să investigheze o cerere API eșuată.

Coduri stabile de eroare

Cod	Stare HTTP	Semnificație	Acțiune sugerată
`public_api_disabled`	503	Apelurile către API-ul public sunt dezactivate temporar.	Reîncearcă mai târziu sau folosește Studio manual.
`api_key_missing`	401	Cererea nu a inclus o cheie API Bearer.	Trimite `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	Cheia nu poate fi verificată.	Verifică cheia și rotește-o dacă este necesar.
`api_key_revoked`	401	Cheia a fost revocată din setări.	Creează o cheie nouă.
`api_key_expired`	401	Cheia nu mai este validă.	Creează o cheie nouă.
`api_scope_denied`	403	Cheia nu are permisiunea necesară.	Creează o cheie cu permisiunea necesară.
`rate_limited`	429	Prea multe cereri în intervalul curent.	Redu ritmul și reîncearcă mai târziu.
`validation_failed`	400	Corpul cererii, modelul, promptul sau parametrii nu sunt valizi.	Compară corpul cererii cu referința modelului.
`not_found`	404	Sarcină cerută nu există sau nu aparține contului.	Verifică ID-ul public al sarcinii și contul.
`webhook_url_rejected`	400	URL-ul endpointului webhook nu este permis.	Folosește un URL HTTPS public fără credențiale, fragmente, localhost sau adrese de rețea privată.
`chat_model_not_supported`	400	Modelul selectat nu este disponibil pentru Chat API.	Citește `/api/v1/models` și alege un model de chat disponibil.
`chat_session_conflict`	409	Sesiunea de chat nu poate fi folosită pentru această cerere.	Folosește o sesiune creată prin API, care aparține aceluiași cont și model.
`chat_attachment_not_supported`	400	Fișierul atașat la chat nu este acceptat.	Încarcă o imagine prin Files API și trimite `file_id`.
`idempotency_conflict`	409	Aceeași cheie de idempotentă a fost refolosită cu date diferite.	Folosește o cheie nouă sau retrimite exact același corp al cererii.
`insufficient_credits`	402	Contul nu are suficiente credite.	Adaugă credite sau alege o cerere cu un cost mai mic.
`internal_error`	500	Cererea nu a putut fi finalizată.	Reîncearcă folosind idempotenta sau contactează asistența cu `requestId`.

Limite de rata

Rivya aplică limite pentru API-ul public la nivel de aplicație, pentru fiecare cheie API. Limita implicită de producție este configurată prin PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Când primești rate_limited, folosește o așteptare exponențială. Nu reîncerca într-o buclă prea rapidă.

Reîncercări idempotente

Trimite Idempotency-Key cu fiecare cerere de producție POST /api/v1/generations și POST /api/v1/chat/completions.

Model recomandat:

generează o cheie unică pentru fiecare cerere logică de generare
refolosește aceeași cheie doar când reîncerci același corp al cererii
stochează ID-ul public returnat alături de propria înregistrare a sarcinii
pentru Chat API, stochează session_id returnat când vrei să continui aceeași conversație
nu refolosi o cheie pentru alt model, prompt sau alți parametri

Dacă rețeaua eșuează după trimitere, reîncearcă folosind același corp al cererii și aceeași Idempotency-Key. Rivya poate returna răspunsul public stocat în loc să creeze o sarcină duplicată.

Decizii de reîncercare

Reîncearcă următoarele erori cu pauze progresiv mai mari:

public_api_disabled
rate_limited
internal_error
erori temporare de rețea

Nu reîncerca următoarele erori fără să schimbi datele de intrare:

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

Erori și limite API

Formă erorii

Coduri stabile de eroare

Limite de rata

Reîncercări idempotente

Decizii de reîncercare

Pagini asociate

Cuprins