# API-Fehlerbehandlung — Fehlertypen, Codes & doc_url > Jeder v1-Fehler ist ein JSON-Objekt mit type, code, message und doc_url — diese Seite dokumentiert die vollständige Taxonomie der Fehlertypen und jeden einzelnen Fehlercode und ist genau das, worauf eine zurückgegebene doc_url verweist. Jede fehlgeschlagene v1-Anfrage – jede Nicht-2xx-Antwort – gibt dasselbe JSON-Format zurück, das unten vollständig aufgeführt ist. Diese Seite ist auch das, worauf die `doc_url` jedes Fehlers verweist: Jeder Code hat seinen eigenen Ankerabschnitt, sodass Sie über eine `doc_url` aus einer tatsächlichen Fehlerantwort direkt zur Erklärung dieses bestimmten Codes gelangen. ## Das Fehlerformat ```json { "error": { "type": "invalid_request_error", "code": "missing_parameter", "message": "A required parameter is missing.", "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter", "param": "file" } } ``` - `type` — die übergeordnete Kategorie dieses Fehlers (siehe Tabelle unten). Nützlich für eine grobe Verzweigung in Ihrem Fehlerbehandlungscode („Ist das ein Authentifizierungs- oder ein Validierungsproblem?“), ohne jeden einzelnen `code` prüfen zu müssen. - `code` — die spezifische, stabile Fehlerkennung. Darauf sollten Sie im Code abgleichen – sie ändert sich nicht, selbst wenn der Wortlaut von `message` später verbessert wird. - `message` — eine für Menschen lesbare Erklärung. Nützlich für Logs und Debugging, nicht zum Parsen gedacht. - `doc_url` — ein direkter Link zum Abschnitt dieser Seite für diesen bestimmten `code`. - `param` — nur bei Validierungsfehlern vorhanden (`missing_parameter`, `invalid_parameter`, `duplicate_field_name`), benennt das spezifische Anfragefeld, das den Fehler verursacht hat. Wird vollständig weggelassen – nicht `null` – wenn nicht zutreffend. ## Fehlertypen Jeder `code` gehört zu genau einem `type`: | Typ | Bedeutung | | --- | --- | | authentication_error | Etwas stimmt nicht mit der Art und Weise, wie (oder ob) Sie die Anfrage authentifiziert haben. | | invalid_request_error | Die Anfrage selbst ist fehlerhaft – ein fehlender oder ungültiger Parameter. | | not_found_error | Die in der URL referenzierte Ressource (eine Dokument-, Batch- oder Vorlagen-ID) existiert nicht oder gehört nicht zu Ihrem Konto. | | insufficient_credits | Ihr Konto hat nicht genügend Credits, um die angeforderte (kostenpflichtige) Aktion auszuführen. | | rate_limit_error | Sie haben die Anfragelimit für diese Endpunktkategorie überschritten – siehe Ratenbegrenzungen . | | internal_error | Bei uns ist etwas schiefgelaufen, nicht bei Ihnen. | ## Ein Sonderfall: `processing_error` `processing_error` ist **kein** `type`, den Sie jemals in einer übergeordneten `{"error": ...}`-Antwort sehen werden. Er führt nie dazu, dass ein API-Aufruf selbst fehlschlägt. Stattdessen beschreibt er ein einzelnes Dokument innerhalb eines Batches, das nicht extrahiert werden konnte – Sie sehen dies als `"status": "failed"` für dieses eine Dokument in einer ansonsten 200-OK `GET /batches/{batch_name}/results`-Antwort, zusammen mit anderen Dokumenten im selben Batch, die erfolgreich verarbeitet wurden. Behandeln Sie einen Dokumentfehler innerhalb eines erfolgreichen API-Aufrufs nicht als Fehler, um den gesamten Batch erneut zu versuchen – prüfen Sie den eigenen `status` jedes Dokuments. ## Fehlercodes ### missing_api_key **Typ:** `authentication_error` · **HTTP-Status:** 401 Es wurde kein API-Schlüssel angegeben. Senden Sie ihn als `Authorization: Bearer `. ### invalid_api_key **Typ:** `authentication_error` · **HTTP-Status:** 401 Der angegebene API-Schlüssel ist ungültig oder das zugehörige Konto ist deaktiviert. ### plan_required **Typ:** `authentication_error` · **HTTP-Status:** 403 Die API ist im Free-Plan nicht verfügbar. Führen Sie ein Upgrade auf Basic oder höher durch, um sie zu nutzen. ### missing_parameter **Typ:** `invalid_request_error` · **HTTP-Status:** 400 Ein erforderlicher Parameter fehlt. Prüfen Sie `param` im Fehlerobjekt, um zu sehen, welcher fehlt. ### invalid_parameter **Typ:** `invalid_request_error` · **HTTP-Status:** 400 Ein Parameter hat einen ungültigen Wert. Prüfen Sie `param` und `message` für Details – dies ist ein Sammelcode, der alles abdeckt, von einer fehlerhaften `crop`-Zeichenkette über einen außerhalb des Bereichs liegenden `limit`-Wert bis hin zu einem Batch, der nichts zu verarbeitendes enthält. ### duplicate_field_name **Typ:** `invalid_request_error` · **HTTP-Status:** 400 Ein Feld mit diesem Namen existiert bereits in dieser Vorlage. Feldnamen müssen innerhalb einer Vorlage eindeutig sein. ### idempotency_key_reused **Typ:** `invalid_request_error` · **HTTP-Status:** 400 Dieser `Idempotency-Key` wurde bereits für eine Anfrage mit anderen Parametern verwendet. Verwenden Sie einen neuen Schlüssel für eine tatsächlich andere Anfrage – siehe [Idempotenz](/developers/guides/idempotency) für das vollständige Verhalten. ### document_not_found **Typ:** `not_found_error` · **HTTP-Status:** 404 Es wurde kein Dokument mit der angegebenen ID gefunden (entweder existiert es nicht oder es gehört nicht zu Ihrem Konto). ### batch_not_found **Typ:** `not_found_error` · **HTTP-Status:** 404 Es wurde kein Batch mit dem angegebenen Namen gefunden. ### template_not_found **Typ:** `not_found_error` · **HTTP-Status:** 404 Es wurde keine Vorlage mit der angegebenen ID gefunden. ### insufficient_credits **Typ:** `insufficient_credits` · **HTTP-Status:** 402 Nicht genügend Credits für diese Aktion. Prüfen Sie vor einem erneuten Versuch unter `GET /account` Ihre aktuellen `available_credits`. ### rate_limit_exceeded **Typ:** `rate_limit_error` · **HTTP-Status:** 429 Zu viele Anfragen. Reduzieren Sie die Frequenz und wiederholen Sie den Vorgang nach dem Zurücksetzen des Fensters – siehe den `X-RateLimit-Reset`-Antwortheader und die Anleitung zu [Ratenbegrenzungen](/developers/guides/rate-limits). ### internal_error **Typ:** `internal_error` · **HTTP-Status:** 500 Ein unerwarteter Fehler ist aufgetreten. Falls dies bestehen bleibt, liegt es an uns, nicht an Ihnen – wenn Sie ihn zuverlässig reproduzieren können, sind das nützliche Informationen, die Sie bei einer Kontaktaufnahme angeben sollten. --- Source: https://imagetotable.ai/de/developers/guides/errors