# Fehler Jeder Endpunkt schlägt auf dieselbe Weise fehl: mit einem HTTP-Status und einem JSON-Umschlag. ```json { "error": { "type": "invalid_request", "code": "invalid_input", "message": "duration must be one of 5, 10.", "param": "duration", "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ], "request_id": null, "doc_url": "https://doitong.com/developers/docs/errors#invalid_input" } } ``` | Feld | Bedeutung | |---|---| | `type` | Übergeordnete Fehlerklasse. Entscheide anhand dieser Angabe, was zu tun ist. | | `code` | Genau­er, stabiler und maschinenlesbarer Grund. Jeder Code hat unten einen eigenen Abschnitt; `doc_url` verweist darauf. | | `message` | Für Menschen lesbare Erklärung, die sicher protokolliert oder einem Entwickler angezeigt werden kann. | | `param` | Der fehlerhafte Eingabeparameter oder Header, sofern vorhanden. | | `details` | Bei Eingabefehlern jedes gefundene Problem: `[{ "param", "message" }]`. | | `request_id` | Die betreffende Anfrage, sofern vorhanden. | Für einen Aufruf, der einen Fehler zurückgibt, werden keine Kosten berechnet. Eine Anfrage, die *nach* ihrer Annahme fehlschlägt, behält den Status `failed`, enthält `error: { "type", "code", "message" }` im Anfrageobjekt und wird automatisch erstattet. ## Typen | Typ | HTTP-Status | Was zu tun ist | |---|---|---| | `invalid_request` | 400, 413 oder 422 | Korrigiere die Anfrage. Ein erneuter Versuch mit demselben Aufruf schlägt wieder fehl. | | `authentication_error` | 401 | Sende einen gültigen Schlüssel in `Authorization: Bearer `. | | `permission_error` | 403 | Verwende einen Schlüssel mit dem erforderlichen Scope. | | `not_found` | 404 | Prüfe die Modell-ID oder Anfrage-ID. | | `insufficient_credits` | 402 | Lade das API-Guthaben auf (`top_up_url` im Fehler). | | `budget_exceeded` | 402 | Das eigene Budget des Schlüssels ist aufgebraucht. Abschließend: Bitte den Besitzer des Schlüssels, es zu erhöhen. | | `conflict` | 409 | Die Ressource befindet sich nicht in einem Zustand, der diesen Aufruf erlaubt. | | `rate_limited` | 429 | Warte `Retry-After` Sekunden und versuche es dann erneut. | | `upstream_error` | 502 | Das Modell-Backend ist fehlgeschlagen. Ein erneuter Versuch mit demselben `Idempotency-Key` ist sicher: Er wird erneut ausgeführt; es wurden keine Kosten berechnet. | | `service_unavailable` | 503 | Die API ist pausiert oder eine Abhängigkeit ist nicht verfügbar. Versuche es später erneut. | | `internal_error` | 500 | Unser Fehler. Versuche es erneut; wenn er bestehen bleibt, kontaktiere den Support mit der Uhrzeit und `request_id`. | ## Codes ### `invalid_request` Allgemeine fehlerhaft formatierte Anfrage (400). ### `invalid_json` Der Body ist kein gültiges JSON (400). ### `invalid_body` Der Body ist gültiges JSON, aber kein Objekt; die Modelleingabe muss ein JSON-Objekt sein (400). ### `body_too_large` Der Body ist größer als 16 MB (413). Lade große Dateien hoch und übergib stattdessen ihre URL (siehe [Dateien](https://doitong.com/developers/docs/files)). ### `invalid_parameter` Ein Abfrageparameter hat einen falschen Wert, zum Beispiel `limit` außerhalb von 1 bis 100, `wait` ist keine Zahl, ein unbekannter `status` oder eine unbekannte `category` oder `storage` ist nicht `permanent` / `temporary` (400). `param` nennt ihn. ### `invalid_category` `GET /openapi.json?category=` nennt eine Kategorie, die nicht existiert (400). `GET https://api.doitong.com/v1/categories` listet sie auf. ### `invalid_cursor` Der `cursor` eines Listenaufrufs gehört nicht zu dieser Liste (400). Beginne ohne Cursor von vorn. ### `invalid_idempotency_key` Der Header `Idempotency-Key` ist leer oder länger als 255 Zeichen (400). ### `invalid_arguments` Ein MCP-Toolaufruf enthält ein fehlendes oder fehlerhaft formatiertes Argument (nur MCP). `param` nennt das Argument. ### `invalid_input` Die Modelleingabe besteht die Validierung nicht (422): ein unbekannter Parameter (die Meldung schlägt den ähnlichsten gültigen Namen vor), ein fehlender erforderlicher Parameter, ein falscher Typ, ein Wert außerhalb der zulässigen Liste oder des zulässigen Bereichs oder sowohl der kanonische als auch der native Name mit unterschiedlichen Werten. `param` ist der erste fehlerhafte Parameter und `details` listet alle auf. Es werden keine Kosten berechnet. ### `unsupported_file` Eine Datei hat einen nicht unterstützten Typ (422), zum Beispiel ein Upload mit einer nicht unterstützten Erweiterung oder ein `content_type`, der nicht mit der Erweiterung übereinstimmt. ### `invalid_webhook_url` `webhook_url` ist keine öffentliche `https://`-URL (422). Private, lokale und einfache `http://`-Adressen werden abgelehnt. ### `missing_api_key` Der Endpunkt benötigt einen API-Schlüssel, aber es wurde keiner gesendet (401). ### `invalid_api_key` Der Schlüssel ist unbekannt, widerrufen oder abgelaufen (401). ### `insufficient_scope` Dem Schlüssel fehlt der für diesen Aufruf erforderliche Scope (403), zum Beispiel `models:run` für eine Ausführung oder `models:read`, um Anfragen und das Guthaben zu lesen. Siehe [Authentifizierung](https://doitong.com/developers/docs/authentication#scopes). ### `account_disabled` Das Konto ist geschlossen oder gesperrt (403). Seine Schlüssel funktionieren nicht mehr. ### `not_found` Der Pfad existiert nicht (404). ### `model_not_found` Kein öffentliches Modell hat diese ID (404). Liste Modelle mit `GET https://api.doitong.com/v1/models` auf. ### `request_not_found` In deinem Konto existiert keine Anfrage mit dieser ID (404). Anfragen anderer Konten sind niemals sichtbar. ### `insufficient_credits` Das **API-Guthaben** des Kontos (API-Credits, 1.000 API-Credits = 1 $ — nicht die Credits der Doitong-Apps) deckt den Preis dieses Aufrufs nicht ab (402). Die Antwort wird gesendet, bevor Kosten entstehen. Der Fehler enthält `top_up_url`; zahle unter [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) Geld ein und versuche es erneut. ```json { "error": { "type": "insufficient_credits", "code": "insufficient_credits", "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance", "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } } ``` ### `budget_exceeded` Der Aufruf würde das eigene Budget des API-Schlüssels in API-Credits überschreiten (402). Das Budget wird vom Besitzer des Schlüssels festgelegt; ein erneuter Versuch hilft nicht, bis es erhöht wird. ### `conflict` Der Aufruf steht im Konflikt mit dem aktuellen Zustand der Ressource (409). ### `idempotency_mismatch` Der `Idempotency-Key` wurde bereits mit einem anderen Body verwendet (409). Verwende für eine neue Operation einen neuen Schlüssel. ### `idempotency_in_progress` Eine Anfrage mit demselben `Idempotency-Key` wird gerade erstellt (409). Versuche es nach einem kurzen Moment erneut, um sie abzurufen. ### `request_active` Die Anfrage befindet sich noch im Status `queued` oder `running`, daher gibt es noch keine Dateien zum Löschen (409). Lösche sie, sobald die Anfrage abgeschlossen ist. ### `not_cancelable` Die Anfrage ist bereits `succeeded` oder `failed` und kann nicht abgebrochen werden (409). ### `rate_limited` Der Schlüssel hat im aktuellen Zeitfenster zu viele Anfragen gestellt (429). Siehe die Header `X-RateLimit-*` und `Retry-After`. ### `too_many_inflight` Das Konto hat bereits 10 Anfragen im Status `queued` oder `running` (429). Starte die nächste, sobald eine davon abgeschlossen ist. ### `upstream_error` Das Modell-Backend hat die Anfrage abgelehnt oder ist fehlgeschlagen (502 bei der Ausführung oder `failed` mit diesem Code bei der Anfrage). Die API-Credits werden erstattet. Wenn das Backend die Eingabe selbst abgelehnt hat, gibt der Aufruf stattdessen `422 invalid_input` mit seiner Meldung zurück. ### `upstream_lost` Das Modell-Backend kennt die Anfrage nicht mehr, daher wird niemals ein Ergebnis eintreffen. Sie endet mit diesem Code im Status `failed` (Typ `upstream_error`) und wird erstattet. Führe sie erneut aus. ### `timeout` Die Anfrage lief länger als ihr Limit (15 Minuten für Bilder, 60 für Video, 30 für alles andere) und wurde beendet. Sie endet mit diesem Code im Status `failed` und wird erstattet. ### `service_unavailable` Die API ist vorübergehend pausiert oder eine Abhängigkeit wie Datei-Uploads ist nicht verfügbar (503). Versuche es später erneut. ### `internal_error` Auf unserer Seite ist etwas schiefgelaufen (500). Versuche es erneut; wenn der Fehler bestehen bleibt, kontaktiere den Support. ### `charge_failed` Das Konto konnte aufgrund eines internen Problems nicht belastet werden (500). Die Anfrage wird als `failed` markiert; es wurde nichts abgebucht. Versuche es erneut. ### `pricing_unavailable` Der Preis des Modells ist nicht konfiguriert, daher kann es derzeit weder bepreist noch ausgeführt werden (500).