API-Fehlercodes

Vollständige Referenz für jeden Fehlercode, den die API zurückgeben kann, mit HTTP-Status, wann er auftritt und wie man ihn behebt.

Fehler-Envelope

Jede Fehlerantwort verwendet dieselbe kanonische JSON-Struktur:

JSON
{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File is too large. Maximum size is 200 MB.",
    "details": { "max_bytes": 209715200, "received_bytes": 240000000 }
  }
}

Prüfen Sie immer auch den HTTP-Status Code — er gibt die grobe Kategorie an (4xx = Client-Fehler, 5xx = Server-Fehler).

Fehlercode-Referenz

CodeHTTPWannWie beheben
NO_FILE 400 Sie haben vergessen, ein file-Feld anzuhängen, oder der Multipart-Upload war fehlerhaft. Senden Sie die Anfrage als multipart/form-data mit einem file-Feld. Für Batch-Endpoints verwenden Sie files[].
INVALID_FORMAT 400 Sie haben to_format vergessen, oder die angeforderte Konvertierung wird nicht unterstützt (z. B. jpg → zzz). Übergeben Sie ein gültiges to_format. Siehe die convert-Referenz für die vollständige Liste der unterstützten Formate.
FILE_TOO_LARGE 413 Die hochgeladene Datei überschreitet das Größenlimit (200 MB Standard, niedriger für einige KI-Tools). Verkleinern/komprimieren Sie die Datei vor dem Upload oder teilen Sie sie in kleinere Stücke auf.
UNSUPPORTED_MIME 415 Der MIME-Typ der Datei ist nicht auf unserer Whitelist (z. B. .exe, .zip, wenn nicht erwartet). Überprüfen Sie Ihr Dateiformat. Prüfen Sie die unterstützten Formate auf der Startseite.
RATE_LIMITED 429 Sie haben eines der 5-stufigen Rate Limits erreicht. Beachten Sie den Retry-After-Header. Siehe Rate Limits.
JOB_NOT_FOUND 404 Die job_id existiert nicht (Tippfehler, nie erstellt) oder ist abgelaufen (Jobs werden 2 Stunden aufbewahrt). Überprüfen Sie, dass die job_id genau 32 hexadezimale Zeichen hat und in den letzten 2 Stunden erstellt wurde.
JOB_EXPIRED 410 Der Job ist älter als 2 Stunden und die konvertierte Datei wurde automatisch gelöscht. Reichen Sie die Konvertierung erneut ein. Laden Sie das Ergebnis immer umgehend nach Abschluss des Jobs herunter.
CONVERSION_FAILED 500 Die Konvertierungs-Engine lief, schlug aber fehl (z. B. beschädigte Quelle, fehlende Abhängigkeiten, interne Exception). Prüfen Sie error.message für Details. Probieren Sie eine andere Datei. Melden Sie wiederholte Fehlschläge über /contact.
BATCH_TOO_LARGE 400 Ihre POST /api/v1/batch-Anfrage enthielt mehr als 20 Dateien. Teilen Sie Ihren Batch in Stücke von ≤20 Dateien auf.
NOT_FOUND 404 Unbekannter Endpoint oder unbekannter Tool-Slug (z. B. /api/v1/tools/foobar). Überprüfen Sie die Schreibweise. Siehe /api/reference für gültige Endpoints.
NOT_IMPLEMENTED 501 Der Endpoint existiert in unserer Dokumentation, ist aber serverseitig noch nicht angebunden (z. B. flip-image). Verwenden Sie einen Workaround (z. B. /api/v1/convert mit img_rotate=flip-h) oder warten Sie, bis die Funktion verfügbar ist.
BANNED 403 Ihre IP hat 10+ Rate-Limit-Ablehnungen innerhalb 1 Stunde ausgelöst und ist nun für 24 Stunden gesperrt. Warten Sie, bis die Sperre abläuft (siehe Retry-After). Bei geteilter IP kontaktieren Sie uns über /contact.
INTERNAL_ERROR 500 Unerwarteter serverseitiger Fehler. Sollte selten sein. Versuchen Sie es nach einigen Sekunden erneut. Wenn es weiterhin auftritt, melden Sie es über /contact mit dem X-Request-Id-Header aus der Antwort.

Der X-Request-Id-Header

Jede API-Antwort (Erfolg oder Fehler) enthält einen X-Request-Id-Header. Wenn Sie ein Problem melden, geben Sie bitte diese ID an, damit wir die Anfrage in unseren Logs finden können:

HTTP headers
X-Request-Id: 4f2dc3b5cc79fa57

Funktion vorschlagen

0 / 2000