Błędy

Rozgałęziaj po kodzie błędu, nigdy po komunikacie. Tabela powstaje z dokumentu OpenAPI.

Błędy

Status	Kod	Znaczenie
400	invalid_request	Błąd schematu. details.path wskazuje pole, które go wywołało.
401	unauthorized	Brakujący lub nieznany klucz API.
402	quota_exceededRetry-After	Wyczerpany miesięczny limit. Retry-After podaje liczbę sekund do początku nowego miesiąca.
403	key_revoked	Klucz istnieje, ale nie może być użyty: został unieważniony albo subskrypcja Engine API tego konta nie jest już aktywna. Pole message mówi, o który przypadek chodzi.
404	not_found	Nie ma takiej trasy — to samo otrzymasz, gdy ścieżka jest poprawna, ale metoda nie.
409	idempotency_conflictRetry-After	Tylko z nagłówkiem Idempotency-Key: klucz użyto już dla innego żądania (idempotency_conflict — użyj nowego klucza) albo pierwsze żądanie z nim wciąż trwa (idempotency_in_progress — ponów po Retry-After, a otrzymasz jego odpowiedź). Nigdy nie jest naliczane.
409	idempotency_in_progressRetry-After	Tylko z nagłówkiem Idempotency-Key: klucz użyto już dla innego żądania (idempotency_conflict — użyj nowego klucza) albo pierwsze żądanie z nim wciąż trwa (idempotency_in_progress — ponów po Retry-After, a otrzymasz jego odpowiedź). Nigdy nie jest naliczane.
413	too_large	Dane wejściowe przekraczają limit (patrz Limity).
429	busyRetry-After	Chwilowy brak wolnych zasobów albo — na każdej ścieżce uwierzytelnianej kluczem — Twój adres wysłał w ciągu minuty zbyt wiele nieznanych kluczy API. Retry-After w sekundach; to nigdy nie obciąża Twojego limitu.
500	internal	Nieoczekiwany błąd albo backend uwierzytelniania jest nieosiągalny (zapytania są wtedy odrzucane — fail closed).
503	service_unavailable	Żądany silnik nie może być teraz obsłużony — silnik nestingu albo asynchroniczny silnik max. Dla max są dwie przyczyny, a pole message mówi która: poziom nie jest wbudowany w to wdrożenie, albo jest wbudowany, ale worker rozwiązujący zadania nie odpowiada. Fail-closed przed zarezerwowaniem wywołania, więc nigdy nic nie kosztuje.
504	solve_timeout	Obliczenia przekroczyły swój twardy limit czasu. Na ścieżkach prostokątnych wymusza go proxy; przy /v1/optimize/nest silnik wymusza własny, krótszy budżet i odpowiada kodem solve_timeout w zwykłej kopercie. Wywołanie, z którego proxy zrezygnowało, nie jest naliczane.

Treść błędu

Każdy błąd generowany przez sam silnik korzysta z tej samej koperty. Rozgałęziaj logikę na polu error, które jest stabilnym kodem; nigdy na message, którego brzmienie może się zmienić między wydaniami. details występuje przy invalid_request, gdzie path wskazuje pole, które wywołało błąd, oraz przy too_large, gdzie max i got podają limit i to, co zostało przesłane.

Wyjątkiem jest treść żądania powyżej limitu rozmiaru: zawiera wtedy maxBytes. Nieznany engine dodaje available, czyli identyfikatory silników akceptowane przez to wdrożenie.

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" }

Zarówno 402, jak i 429 zwracają nagłówek Retry-After w sekundach. Przy 402 odlicza on czas do zerowania limitu o 00:00 UTC pierwszego dnia następnego miesiąca; przy 429 jest to krótkie wstrzymanie, a 429 nigdy nie zużywa limitu — zarezerwowane wywołanie jest oddawane.
Odmowy publicznego klucza demo używają tej samej koperty: poza jego zakresem (nesting, silnik max, usage, jobs, import, zadanie powyżej jego limitów rozmiaru) 403 key_revoked z details.reason "demo_scope"; przy jego limicie częstotliwości 429 busy z details.reason "demo_rate_limit" i details.limit. Obie niosą details.testKeyUrl, gdzie tworzy się darmowy klucz testowy, a każda odpowiedź demo ma nagłówek X-CutOptim-Demo: true.
Błąd routingu odpowiada kodem not_found, który celowo znajduje się poza powyższą listą, bo generuje go router, a nie kontrakt API. Otrzymasz 404, a nie 405, gdy ścieżka jest poprawna, ale metoda nie: wszystkie cztery endpointy optymalizacji przyjmują wyłącznie POST.
Na ścieżkach prostokątnych 504 pochodzi z reverse proxy, a nie z silnika, więc jego treść należy do proxy i nie jest tą kopertą JSON; pojedyncze zadanie w granicach poniższych limitów wejściowych mieści się w nim z dużym zapasem, ale kilka najcięższych zadań naraz może go przekroczyć w kolejce — a wywołanie, z którego proxy zrezygnowało, nie jest naliczane.
Wyjątkiem jest /v1/optimize/nest: to obliczenie jest podprocesem z własnym budżetem, celowo utrzymanym poniżej limitu proxy — przekroczenie czasu używa tam tej koperty, z kodem solve_timeout.

Czy któryś silnik nie działa? Strona statusu pokazuje na żywo stan witryny, Engine API, silnika nestingu i asynchronicznego silnika max: Status usługi ↗