Ghid operator pentru Venice errors

Ce face

venice-errors este capabilitatea care te ajută să tratezi corect erorile Venice API: ce repari, ce plătești, ce retry-uiești și unde te oprești. Nu toate erorile au aceeași formă, iar retry-ul automat pe orice non-OK produce costuri, zgomot și bug-uri mai greu de diagnosticat.

Skill-ul descrie patru forme de body:

StandardError, forma simplă pentru multe erori:

{ "error": "Unauthorized" }

DetailedError, folosit la unele 400 Bad Request, cu detalii de validare în details și issues. details este un arbore Zod cu _errors, nu o hartă plată.

ContentViolationError, folosit la 422 pe căi de generare când promptul lovește content policy. suggested_prompt apare în prezent pentru audio generation, nu trebuie presupus generic pentru image sau video.

X402InferencePaymentRequired, folosit la 402 Payment Required când autentificarea este SIWE și creditul x402 este insuficient. Se recunoaște prin code: "PAYMENT_REQUIRED".

Vezi și All guides pentru restul ghidurilor.

Când îmi folosește

Îți folosește când integrezi sau depanezi apeluri Venice API și primești statusuri precum 400, 401, 402, 403, 415, 422, 429, 500, 503 sau 504.

Folosește-l mai ales când scrii un handler centralizat de erori, o politică de retry, mesaje afișabile utilizatorului sau logging pentru suport.

Cazuri tipice:

400: request invalid. Dacă există details / issues, le afișezi într-o formă citibilă și repari inputul. Nu retry.

401: autentificare lipsă sau invalidă. Repari credentialele. Nu retry.

402: pentru Bearer, utilizatorul trebuie să își refacă creditul în cont. Pentru SIWE cu code: "PAYMENT_REQUIRED", rulezi flow-ul x402.

403: autentificare validă, dar fără dreptul necesar. Investighezi entitlement-ul, limita sau wallet-ul. Nu retry.

415: Content-Type greșit. Repari header-ele. Nu retry.

422: content policy sau validare, în funcție de endpoint. Dacă există suggested_prompt, retry o singură dată doar cu consimțământul utilizatorului.

429: rate limit. Respecți header-ele și faci backoff cu jitter.

500, 503, 504: retry limitat cu exponential backoff; pentru 504 pe chat cu contexte mari, redu promptul sau folosește streaming.

Cum îl invoc / declanșez

Numele canonic al capabilității este:

venice-errors

Nu există în sursa canonică o comandă universală publică sau un trigger garantat. Într-un runtime cu mecanism de skills, îl încarci prin mecanismul acelui runtime. În documentație sau cod, îl tratezi ca referință pentru interpretarea erorilor Venice API, nu ca endpoint Venice separat.

Nu inventa disponibilitate, comenzi CLI, automatizări sau integrare cu un anumit agent dacă mediul tău nu le documentează explicit.

Exemplu practic

Ai un wrapper care primește un Response non-OK.

Pentru 400, parsezi body-ul. Dacă vezi details sau issues, le parcurgi și le arăți utilizatorului ca erori de câmp. Dacă nu, afișezi mesajul simplu din error. Nu retry.

Pentru 401, 403 și 415, oprești fluxul și raportezi cauza probabilă: auth invalid, lipsă entitlement sau Content-Type greșit.

Pentru 402, separi Bearer de SIWE. La Bearer, semnalezi credit insuficient și ceri top-up în cont. La SIWE, body-ul are code: "PAYMENT_REQUIRED", iar header-ul PAYMENT-REQUIRED conține un obiect x402 v2 encodat base64. Header-ul este pentru client protocol-level; body-ul este mai bun pentru mesajul uman.

Pentru 422, nu rescrii promptul fără acord. Dacă suggested_prompt există, îl prezinți utilizatorului și faci cel mult un retry cu varianta acceptată. Dacă nu există, ceri modificarea inputului.

Pentru 429, onorezi Retry-After când există. Altfel folosești X-RateLimit-Reset și adaugi jitter. Ține cont că unele rute pot lovi și limite de credit sau concurență, nu doar per-minute.

Pentru 500 / 503 / 504, folosești 0.5s, 1s, 2s, 4s, 8s, capped la aproximativ 30s, cu maximum 3–5 retry-uri. Unde endpoint-ul suportă, adaugă Idempotency-Key.

Output / unde aterizează

Output-ul capabilității este o decizie operațională: repară request-ul, cere auth valid, cere top-up, rulează x402, aplică backoff, schimbă modelul, scurtează promptul sau oprește fără retry.

Într-o integrare reală, rezultatul trebuie să ajungă în handler-ul central de erori: excepții structurate, mesaje sigure pentru utilizator, logging cu X-Request-ID când există și politică de retry controlată.

Pentru streaming, erorile pot veni ca evenimente SSE cu data: {"error": ...} deși HTTP status rămâne 200. Tratează-le ca terminale: stream-ul s-a închis și nu mai poți schimba statusul retroactiv.

Limite / gotchas

Nu presupune că toate 400 au DetailedError; multe au doar { "error": "..." }.

Nu presupune că toate 422 includ suggested_prompt; în prezent acesta este specific pipeline-ului audio.

Nu confunda body-ul X402InferencePaymentRequired cu header-ul PAYMENT-REQUIRED. Sunt obiecte diferite.

Nu retry-ui 400, 401, 403 sau 415.

Nu ignora Retry-After pe 429.

Nu trata un 402 de discovery din flow-ul x402 ca eșec final; poate fi pasul normal prin care clientul află cerințele de plată.

Nu loga credentiale, token-uri, payment headers sau conținut sensibil. Păstrează doar identificatori de corelare, status, endpoint generic și mesajul de eroare necesar diagnosticului.