Erori

Ramifică după codul de eroare, niciodată după mesaj. Tabelul este generat din documentul OpenAPI.

Erori

Stare	Cod	Semnificație
400	invalid_request	Eroare de schemă. details.path indică câmpul problematic.
401	unauthorized	Cheie API lipsă sau necunoscută.
402	quota_exceededRetry-After	Cota lunară a fost atinsă. Retry-After indică secundele rămase până la începutul lunii următoare.
403	key_revoked	Cheia există, dar nu poate fi folosită: a fost revocată sau abonamentul Engine API al contului nu mai este activ. Câmpul message spune care dintre ele.
404	not_found	Nu există o astfel de rută — este și răspunsul pe care îl primești pentru calea corectă cu metoda greșită.
409	idempotency_conflictRetry-After	Doar cu antetul Idempotency-Key: cheia a fost deja folosită pentru altă cerere (idempotency_conflict — folosiți o cheie nouă) sau prima cerere cu ea încă rulează (idempotency_in_progress — reîncercați după Retry-After pentru a primi răspunsul ei). Nu se taxează niciodată.
409	idempotency_in_progressRetry-After	Doar cu antetul Idempotency-Key: cheia a fost deja folosită pentru altă cerere (idempotency_conflict — folosiți o cheie nouă) sau prima cerere cu ea încă rulează (idempotency_in_progress — reîncercați după Retry-After pentru a primi răspunsul ei). Nu se taxează niciodată.
413	too_large	Intrare peste o limită (vezi Limite).
429	busyRetry-After	Capacitate atinsă momentan sau — pe orice rută autentificată cu cheie — adresa ta a trimis prea multe chei API necunoscute într-un minut. Retry-After în secunde; acest răspuns nu se scade niciodată din cota ta.
500	internal	Eroare neașteptată sau backendul de autentificare este inaccesibil (cererile sunt respinse — fail closed).
503	service_unavailable	Un motor cerut nu poate fi servit acum — motorul de nesting sau motorul max asincron. Pentru max sunt două cauze, iar câmpul message spune care: nivelul nu este inclus în acest deployment, sau este inclus dar worker-ul care rezolvă lucrările nu răspunde. Fail-closed înainte ca un apel să fie rezervat, deci nu costă niciodată nimic.
504	solve_timeout	Rezolvarea a depășit limita sa strictă de timp. Pe traseele rectangulare o impune proxy-ul; pe /v1/optimize/nest motorul impune propriul buget, mai scurt, și răspunde cu solve_timeout în plicul obișnuit. Un apel abandonat de proxy nu este taxat.

Corpul erorii

Fiecare eroare produsă de motorul propriu-zis folosește același înveliș. Ramifică logica după error, care este un cod stabil; niciodată după message, a cărui formulare se poate schimba de la o versiune la alta. details este prezent la invalid_request, unde path numește câmpul problematic, și la too_large, unde max și got indică plafonul și valoarea pe care ai trimis-o.

Excepția este un corp de cerere peste plafonul de mărime: acesta poartă în schimb maxBytes. Un engine necunoscut adaugă available, id-urile de engine pe care le acceptă această instalare.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_request",
  "message": "parts[0].h: must be greater than 0",
  "details": { "path": "parts[0].h" }
}

HTTP/1.1 402 Payment Required
Retry-After: 41400
Content-Type: application/json; charset=utf-8

{ "error": "quota_exceeded", "message": "monthly quota exhausted" }

Atât 402, cât și 429 conțin un header Retry-After exprimat în secunde. La 402 numără invers până la resetarea cotei, la 00:00 UTC în prima zi a lunii următoare; la 429 este o scurtă pauză înainte de reîncercare, iar un 429 nu consumă niciodată cotă — apelul rezervat este restituit.
Refuzurile cheii demo publice folosesc același plic: în afara domeniului ei (nesting, motorul max, usage, jobs, import, o lucrare peste limitele ei de mărime) un 403 key_revoked cu details.reason "demo_scope"; la limita ei de frecvență un 429 busy cu details.reason "demo_rate_limit" și details.limit. Ambele poartă details.testKeyUrl, unde se creează o cheie de test gratuită, iar fiecare răspuns demo are antetul X-CutOptim-Demo: true.
O eroare de rutare răspunde cu not_found, un cod aflat intenționat în afara listei de mai sus, pentru că îl produce routerul, nu contractul API. Primești 404, și nu 405, atunci când calea este corectă, dar metoda este greșită: toate cele patru endpointuri de optimizare acceptă doar POST.
Pe traseele rectangulare, 504 vine de la reverse proxy, nu de la motor, așa că corpul răspunsului este al proxy-ului și nu acest înveliș JSON; o singură lucrare în limitele de intrare de mai jos rămâne mult sub ea, dar mai multe dintre cele mai grele lucrări sosite deodată o pot depăși în coadă — iar un apel abandonat de proxy nu este taxat. /v1/optimize/nest este excepția: acea rezolvare este un subproces cu buget propriu, ținut intenționat sub limita proxy-ului, deci acolo un timeout folosește acest înveliș, cu codul solve_timeout.

A căzut un motor? Pagina de stare arată în timp real starea site-ului, a Engine API, a motorului de nesting și a motorului asincron max: Starea serviciului ↗