Fehler

Verzweigen Sie auf den Fehlercode, nie auf die Meldung. Die Tabelle entsteht aus dem OpenAPI-Dokument.

Fehler

Status	Code	Bedeutung
400	invalid_request	Schema-Fehler. details.path verweist auf das betreffende Feld.
401	unauthorized	API-Schlüssel fehlt oder ist unbekannt.
402	quota_exceededRetry-After	Monatskontingent erreicht. Retry-After gibt die Sekunden bis zum Monatswechsel an.
403	key_revoked	Der Schlüssel existiert, darf aber nicht verwendet werden: Er wurde widerrufen, oder das Engine-API-Abonnement des Kontos ist nicht mehr aktiv. Die message sagt, was von beidem.
404	not_found	Diese Route gibt es nicht — dasselbe erhalten Sie für den richtigen Pfad mit der falschen Methode.
409	idempotency_conflictRetry-After	Nur mit dem Header Idempotency-Key: Der Schlüssel wurde bereits für eine andere Anfrage verwendet (idempotency_conflict — neuen Schlüssel verwenden), oder die erste Anfrage mit ihm läuft noch (idempotency_in_progress — nach Retry-After wiederholen, dann kommt ihre Antwort). Wird nie berechnet.
409	idempotency_in_progressRetry-After	Nur mit dem Header Idempotency-Key: Der Schlüssel wurde bereits für eine andere Anfrage verwendet (idempotency_conflict — neuen Schlüssel verwenden), oder die erste Anfrage mit ihm läuft noch (idempotency_in_progress — nach Retry-After wiederholen, dann kommt ihre Antwort). Wird nie berechnet.
413	too_large	Eingabe über einem Limit (siehe Limits).
429	busyRetry-After	Kapazität momentan ausgeschöpft, oder — auf jedem Pfad mit Schlüssel — Ihre Adresse hat binnen einer Minute zu viele unbekannte API-Schlüssel gesendet. Retry-After in Sekunden; das zählt nie auf Ihr Kontingent.
500	internal	Unerwarteter Fehler, oder das Auth-Backend ist nicht erreichbar (Anfragen werden dann abgewiesen — fail closed).
503	service_unavailable	Eine angeforderte Engine kann derzeit nicht bedient werden — die Nesting-Engine oder die asynchrone max-Engine. Bei max gibt es zwei Ursachen, und die message sagt welche: Die Stufe ist in dieses Deployment nicht eingebaut, oder sie ist eingebaut, aber der Worker, der die Jobs löst, antwortet nicht. Fail-closed vor der Reservierung eines Aufrufs, kostet also nie etwas.
504	solve_timeout	Die Berechnung hat ihre harte Zeitgrenze überschritten. Auf den rechteckigen Pfaden setzt der Proxy sie durch; bei /v1/optimize/nest setzt die Engine ihr eigenes, kürzeres Budget durch und antwortet mit solve_timeout im normalen Umschlag. Ein Aufruf, den der Proxy aufgegeben hat, wird nicht berechnet.

Fehler-Body

Jeder Fehler, den die Engine selbst erzeugt, verwendet denselben Umschlag. Verzweigen Sie über error — ein stabiler Code —, niemals über message, dessen Wortlaut sich zwischen Releases ändern kann. details ist bei invalid_request vorhanden, wo path das betreffende Feld benennt, und bei too_large, wo max und got das Limit und Ihren gesendeten Wert angeben.

Ausnahme ist ein Request-Body über dem Größenlimit: Er trägt stattdessen maxBytes. Eine unbekannte engine ergänzt available, die Engine-IDs, die dieses Deployment akzeptiert.

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 und 429 tragen beide einen Retry-After-Header in Sekunden. Bei 402 zählt er bis zum Zurücksetzen des Kontingents am 1. des Folgemonats um 00:00 UTC herunter; bei 429 ist es ein kurzer Back-off, und ein 429 verbraucht nie Kontingent — der reservierte Aufruf wird zurückgegeben.
Ablehnungen des öffentlichen Demo-Schlüssels nutzen denselben Umschlag: außerhalb seines Umfangs (Nesting, die max-Engine, usage, jobs, import, ein Job über seinen Größengrenzen) ein 403 key_revoked mit details.reason "demo_scope"; an seinem Ratenlimit ein 429 busy mit details.reason "demo_rate_limit" und details.limit.
Beide tragen details.testKeyUrl, wo ein kostenloser Testschlüssel angelegt wird, und jede Demo-Antwort hat den Header X-CutOptim-Demo: true.
Ein Routing-Fehler antwortet mit not_found — ein Code, der bewusst außerhalb der Liste oben steht, weil ihn der Router erzeugt und nicht der API-Vertrag. Sie erhalten 404 und nicht 405, wenn der Pfad stimmt, die Methode aber nicht: alle vier Optimierungs-Endpoints nehmen ausschließlich POST.
Auf den rechteckigen Pfaden kommt 504 vom Reverse-Proxy, nicht von der Engine — der Body gehört deshalb dem Proxy und ist nicht dieser JSON-Umschlag; ein einzelner Job innerhalb der unten genannten Eingabelimits bleibt weit darunter, mehrere der schwersten Jobs gleichzeitig können in der Warteschlange aber darüber kommen — und ein Aufruf, den der Proxy aufgegeben hat, wird nicht berechnet. /v1/optimize/nest ist die Ausnahme: Diese Berechnung ist ein Subprozess mit eigenem Budget, das bewusst unter der Proxy-Grenze liegt — ein Timeout dort verwendet also diesen Umschlag, mit dem Code solve_timeout.

Ist eine Engine ausgefallen? Die Statusseite zeigt live den Zustand der Website, der Engine API, der Nesting-Engine und der asynchronen max-Engine: Dienststatus ↗