Chyby

Větvěte podle chybového kódu, nikdy podle zprávy. Tabulka vzniká z dokumentu OpenAPI.

Chyby

Stav	Kód	Význam
400	invalid_request	Chyba schématu. details.path ukazuje na problematické pole.
401	unauthorized	Chybějící nebo neznámý API klíč.
402	quota_exceededRetry-After	Vyčerpaná měsíční kvóta. Retry-After udává počet sekund do začátku nového měsíce.
403	key_revoked	Klíč existuje, ale nesmí být použit: byl zneplatněn, nebo předplatné Engine API pro tento účet už není aktivní. Pole message řekne, o který případ jde.
404	not_found	Taková cesta neexistuje — a totéž dostanete, když je cesta správná, ale metoda špatná.
409	idempotency_conflictRetry-After	Jen s hlavičkou Idempotency-Key: klíč už byl použit pro jiný požadavek (idempotency_conflict — použijte nový klíč), nebo první požadavek s ním ještě běží (idempotency_in_progress — zopakujte po Retry-After a dostanete jeho odpověď). Nikdy se neúčtuje.
409	idempotency_in_progressRetry-After	Jen s hlavičkou Idempotency-Key: klíč už byl použit pro jiný požadavek (idempotency_conflict — použijte nový klíč), nebo první požadavek s ním ještě běží (idempotency_in_progress — zopakujte po Retry-After a dostanete jeho odpověď). Nikdy se neúčtuje.
413	too_large	Vstup překračuje limit (viz Limity).
429	busyRetry-After	Momentálně plná kapacita, nebo — na kterékoli cestě ověřované klíčem — vaše adresa během minuty poslala příliš mnoho neznámých API klíčů. Retry-After v sekundách; do vaší kvóty se to nikdy nepočítá.
500	internal	Neočekávaná chyba, nebo je nedostupný autentizační backend (požadavky se odmítají — fail closed).
503	service_unavailable	Požadované jádro nelze právě teď obsloužit — nesting jádro nebo asynchronní jádro max. U max jsou dvě příčiny a pole message řekne která: vrstva není v tomto nasazení zabudovaná, nebo zabudovaná je, ale worker, který úlohy řeší, neodpovídá. Fail-closed před rezervací volání, takže vás to nikdy nic nestojí.
504	solve_timeout	Výpočet překročil svůj tvrdý časový limit. Na obdélníkových cestách jej vynucuje proxy; u /v1/optimize/nest vynucuje jádro vlastní, kratší rozpočet a odpovídá kódem solve_timeout v běžné obálce. Volání, které proxy vzdala, se nezapočítává.

Tělo chyby

Každá chyba, kterou vytvoří samotné jádro, používá stejnou obálku. Rozhodujte se podle error, což je stabilní kód; nikdy podle message, jehož formulace se mezi vydáními může změnit. details je přítomné u invalid_request, kde path pojmenovává problematické pole, a u too_large, kde max a got udávají limit a to, co jste poslali.

Výjimkou je tělo požadavku nad limitem velikosti: nese místo toho maxBytes. Neznámý engine přidá available, tedy ID enginů, které toto nasazení přijímá.

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

402 i 429 nesou hlavičku Retry-After v sekundách. U 402 odpočítává čas do resetu kvóty v 00:00 UTC prvního dne následujícího měsíce; u 429 jde o krátké počkání a 429 nikdy nespotřebuje kvótu — rezervované volání se vrací zpět.
Odmítnutí veřejného demo klíče používají stejnou obálku: mimo jeho rozsah (nesting, engine max, usage, jobs, import, úloha nad jeho limity velikosti) 403 key_revoked s details.reason "demo_scope"; na jeho rychlostním limitu 429 busy s details.reason "demo_rate_limit" a details.limit. Obě nesou details.testKeyUrl, kde se vytvoří bezplatný testovací klíč, a každá demo odpověď má hlavičku X-CutOptim-Demo: true.
Chyba směrování odpovídá kódem not_found, který záměrně není v seznamu výše, protože jej vytváří router, a ne kontrakt API. Když je cesta správná, ale metoda špatná, dostanete 404, a ne 405: všechny čtyři optimalizační endpointy přijímají jen POST.
Na obdélníkových cestách přichází 504 z reverzní proxy, ne z jádra, takže jeho tělo patří proxy, a ne této JSON obálce; jedna úloha v rámci vstupních limitů níže se spočítá hluboko pod ním, ale několik nejtěžších úloh najednou se za něj může ve frontě dostat — a volání, které proxy vzdala, se nezapočítává.
Výjimkou je /v1/optimize/nest: ten výpočet je podproces s vlastním rozpočtem, záměrně drženým pod limitem proxy — vypršení času tam tedy používá tuto obálku, s kódem solve_timeout.

Nefunguje některé jádro? Stavová stránka ukazuje živý stav webu, Engine API, nestingového jádra a asynchronního jádra max: Stav služby ↗