Fileverity-API-Dokumentation

Fehler

Das Fehlerformat der Fileverity-API, HTTP-Statuscodes und die vollständige Tabelle der Fehlercodes, mit Hinweisen, welche Fehler Sie wiederholen sollten.

Als Markdown ansehenAktualisiert am 2026-11-04

Fehler werden mit einem Standard-HTTP-Status und einem JSON-Antworttext mit einem stabilen code gemeldet. Verzweigen Sie anhand von code, nicht anhand von message: Meldungen können sich ändern.

{  "error": {    "type": "invalid_request_error",    "code": "invalid_parameter",    "message": "Unrecognized parameter: files.",    "param": "files",    "request_id": "req_4mQ9cX2vB7nP1sK8tL3wR6yZ"  }}

Feld	Beschreibung
`error.type`	Die Kategorie. Jeder Typ entspricht einer HTTP-Statusfamilie, die unten aufgeführt ist.
`error.code`	Eine stabile, maschinenlesbare Kennung.
`error.message`	Eine für Menschen lesbare Erklärung. Sie kann das betroffene Feld oder Limit nennen.
`error.param`	Das Feld der Anfrage, das den Fehler verursacht hat, oder `null`.
`error.request_id`	Die ID dieser Anfrage, auch im Antwort-Header `x-request-id`. Geben Sie sie an, wenn Sie den Support unter hello@fileverity.com kontaktieren.

Fehlertypen

Typ	Status	Bedeutung
`invalid_request_error`	400, 413, 415, 422	Die Anfrage ist fehlerhaft aufgebaut oder verstößt gegen ein Limit. Korrigieren Sie die Anfrage; eine unveränderte Wiederholung schlägt erneut fehl.
`authentication_error`	401	Der API-Schlüssel fehlt oder ist ungültig.
`billing_error`	402	Das Guthaben oder ein Ausgabenlimit verhindert die Anfrage. Laden Sie Guthaben auf oder erhöhen Sie das Limit.
`not_found_error`	404	Die Ressource existiert nicht, ist abgelaufen oder gehört zu einem anderen Workspace.
`conflict_error`	409	Die Anfrage steht im Konflikt mit dem aktuellen Zustand.
`rate_limit_error`	429	Zu viele Anfragen oder zu viele ausstehende Uploads. Warten Sie bei `rate_limited` die Sekunden aus `retry-after` ab. `pending_files_limit` enthält kein `retry-after`: Verwenden oder löschen Sie die Dateien, oder warten Sie, bis sie ablaufen.
`api_error`	500, 502, 503	Ein Problem auf unserer Seite oder ausgelastete Kapazität. Diese Anfragen wurden nicht berechnet. Wiederholen Sie sie mit Backoff. Bei `service_unavailable` enthält die Antwort den Header `retry-after`.

Was Sie wiederholen sollten

Wiederholen Sie rate_limited nach den Sekunden aus retry-after, und internal_error, analysis_failed und service_unavailable mit exponentiellem Backoff (bei service_unavailable beginnen Sie mit den Sekunden aus retry-after). Senden Sie denselben Idempotency-Key, damit eine Wiederholung nicht doppelt ausgeführt werden kann. Siehe Idempotenz.
Wiederholen Sie nach einer Wartezeit idempotency_in_progress.
Wiederholen Sie nicht andere 4xx-Fehler, bis Sie die Anfrage oder den Zustand des Kontos ändern.
Eine Prüfung, die mit einem Fehler endet, wird nicht berechnet.

Sie kommen nicht weiter? Schreiben Sie an hello@fileverity.com oder nutzen Sie die Kontaktseite und geben Sie die Anfrage-ID an.

Fehlercodes

Diese Tabelle wird aus den Fehlerdefinitionen der API selbst erzeugt.

Code	Status	Typ	Meldung
`invalid_json`	400	`invalid_request_error`	Der Anfragetext muss ein JSON-Objekt sein.
`missing_parameter`	400	`invalid_request_error`	Ein erforderlicher Parameter fehlt.
`invalid_parameter`	400	`invalid_request_error`	Ein Parameter hat einen ungültigen Wert.
`text_too_short`	400	`invalid_request_error`	Der Text ist zu kurz für eine Auswertung. Senden Sie mindestens 100 Wörter.
`text_too_long`	413	`invalid_request_error`	Der Text überschreitet 100.000 Zeichen. Teilen Sie ihn auf mehrere Anfragen auf.
`unsupported_media_type`	415	`invalid_request_error`	Senden Sie den Anfragetext als JSON mit dem Header „Content-Type: application/json“.
`unsupported_language`	400	`invalid_request_error`	Der Text liegt nicht in einer unterstützten Sprache vor. Unterstützte Sprachen sind en, fr, de, es und zh.
`file_not_found`	400	`invalid_request_error`	Die hochgeladene Datei wurde nicht gefunden oder ist abgelaufen. Laden Sie sie erneut hoch.
`unsupported_file`	415	`invalid_request_error`	Das Dateiformat wird für dieses Modell nicht unterstützt.
`file_too_large`	413	`invalid_request_error`	Die Datei überschreitet das Größenlimit für dieses Modell.
`too_many_pixels`	413	`invalid_request_error`	Das Bild hat mehr als 40 Megapixel.
`too_many_pages`	413	`invalid_request_error`	Das Dokument hat mehr als 100 Seiten.
`document_too_long`	413	`invalid_request_error`	Das Dokument enthält zu viel Text, um ihn in einer Anfrage zu analysieren.
`invalid_file`	422	`invalid_request_error`	Die Datei ist beschädigt oder kann nicht gelesen werden.
`password_required`	422	`invalid_request_error`	Das Dokument ist verschlüsselt. Senden Sie sein Passwort mit, um es zu analysieren.
`wrong_password`	422	`invalid_request_error`	Das Dokumentpasswort ist falsch.
`not_examinable`	422	`invalid_request_error`	Das Dokument enthält keinen Text, keine Fotos und keine Struktur, die sich untersuchen ließen. Es wurde nichts berechnet.
`missing_api_key`	401	`authentication_error`	Es wurde kein API-Schlüssel angegeben. Senden Sie ihn im Header „Authorization: Bearer fv_live_...“.
`invalid_api_key`	401	`authentication_error`	Der API-Schlüssel ist ungültig oder wurde widerrufen.
`insufficient_balance`	402	`billing_error`	Ihr Guthaben reicht für diese Anfrage nicht aus. Laden Sie Ihr Guthaben in der Konsole auf.
`spend_limit_reached`	402	`billing_error`	Dieser API-Schlüssel hat sein monatliches Ausgabenlimit erreicht. Erhöhen Sie das Limit in der Konsole oder warten Sie bis zum nächsten Monat (UTC).
`not_found`	404	`not_found_error`	Die angeforderte Ressource existiert nicht.
`model_not_found`	404	`not_found_error`	Das Modell existiert nicht oder ist nicht verfügbar.
`not_cancelable`	409	`conflict_error`	Die Analyse kann nicht mehr abgebrochen werden.
`canceled`	409	`conflict_error`	Die Analyse wurde abgebrochen. Es wurde nichts berechnet.
`idempotency_mismatch`	409	`conflict_error`	Dieser Idempotency-Key wurde bereits mit einem anderen Anfragetext verwendet.
`idempotency_in_progress`	409	`conflict_error`	Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet. Versuchen Sie es in Kürze erneut.
`pending_files_limit`	429	`rate_limit_error`	Dieser Workspace hat zu viele ausstehende Uploads. Analysieren oder löschen Sie hochgeladene Dateien oder warten Sie bis zu 24 Stunden, bis sie ablaufen.
`rate_limited`	429	`rate_limit_error`	Zu viele Anfragen. Versuchen Sie es nach der im Header Retry-After angegebenen Anzahl von Sekunden erneut.
`internal_error`	500	`api_error`	Die Anfrage konnte nicht abgeschlossen werden. Wiederholen Sie sie; falls das Problem weiterhin besteht, wenden Sie sich mit der Anfrage-ID an den Support.
`analysis_failed`	502	`api_error`	Die Analyse konnte nicht abgeschlossen werden. Es wurde nichts berechnet; wiederholen Sie sie und wenden Sie sich mit der Anfrage-ID an den Support, falls sie erneut fehlschlägt.
`service_unavailable`	503	`api_error`	Der Dienst ist vorübergehend nicht verfügbar oder ausgelastet. Es wurde nichts berechnet; versuchen Sie es nach der im Header Retry-After angegebenen Anzahl von Sekunden erneut.

Nur in der Konsole auftretende Codes

Diese Codes werden von den eigenen Endpunkten der Konsole zurückgegeben, die mit Ihrer Anmeldesitzung arbeiten. Anfragen mit einem API-Schlüssel liefern sie nicht zurück.

Code	Status	Typ	Meldung
`session_required`	401	`authentication_error`	Melden Sie sich an, um fortzufahren.
`forbidden`	403	`permission_error`	Sie haben dafür keine Berechtigung.
`invite_invalid`	404	`not_found_error`	Diese Einladung ist ungültig, abgelaufen oder bereits verwendet.
`invite_mismatch`	403	`permission_error`	Diese Einladung wurde an eine andere E-Mail-Adresse gesendet.
`invite_limit`	409	`conflict_error`	Dieser Workspace hat bereits die maximale Anzahl offener Einladungen. Widerrufen Sie zuerst eine.
`last_owner`	409	`conflict_error`	Ein Workspace braucht mindestens einen Inhaber. Ernennen Sie zuerst ein anderes Mitglied zum Inhaber.
`webhook_limit`	409	`conflict_error`	Dieser Workspace hat bereits die maximale Anzahl von Webhook-Endpunkten. Löschen Sie zuerst einen.
`key_limit`	409	`conflict_error`	Dieser Workspace hat bereits die maximale Anzahl aktiver API-Schlüssel. Widerrufen Sie zuerst einen.

Fehler

Fehlertypen#

Was Sie wiederholen sollten#

Fehlercodes#

Nur in der Konsole auftretende Codes#

Fehlertypen

Was Sie wiederholen sollten

Fehlercodes

Nur in der Konsole auftretende Codes