Leitfaden

Fehlerbehandlung

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

{
  "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:

TypBedeutung
authentication_errorEtwas stimmt nicht mit der Art und Weise, wie (oder ob) Sie die Anfrage authentifiziert haben.
invalid_request_errorDie Anfrage selbst ist fehlerhaft – ein fehlender oder ungültiger Parameter.
not_found_errorDie in der URL referenzierte Ressource (eine Dokument-, Batch- oder Vorlagen-ID) existiert nicht oder gehört nicht zu Ihrem Konto.
insufficient_creditsIhr Konto hat nicht genügend Credits, um die angeforderte (kostenpflichtige) Aktion auszuführen.
rate_limit_errorSie haben die Anfragelimit für diese Endpunktkategorie überschritten – siehe Ratenbegrenzungen.
internal_errorBei 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 <key>.

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 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.

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.

📮 contact email: [email protected]