Fehlercodes

Fachliche Fehler beantwortet die REST-API mit einem Körper der Form:

{ "error": "Zugriff verweigert.", "code": "access-denied" }

code ist stabil und sprachunabhängig — Integrationen sollten ausschließlich darauf prüfen. error ist lokalisiert (9 Sprachen, gemäß Accept-Language, Standard Deutsch). Validierungsfehler der Eingabedaten kommen davon abweichend als Standard-ProblemDetails (HTTP 400 mit errors-Wörterbuch).

Allgemeine Codes

Code	HTTP	Bedeutung
`tenant-not-found`	400	Mandant (Kürzel/Host) existiert nicht
`access-denied`	403	Fehlende Berechtigung (bewusst generisch)
`superadmin-required`	403	Endpunkt erfordert Superadmin-Rechte
`superadmin-only`	403	Nur Superadmins dürfen diese Einstellung ändern
`login-not-allowed`	401	Login für diesen Mandanten nicht erlaubt
`no-file`	400	Keine Datei übermittelt
`name-required`	400	Name ist erforderlich
`password-policy`	400	Passwort verletzt die Passwort-Richtlinie (Text nennt die Regel)
`key-not-editable`	400	Einstellungs-Schlüssel ist nicht über die API änderbar
`slug-reserved`	400	Mandanten-Kürzel ist reserviert (z. B. für den Demo-Modus)
`unknown-mode`	400	Unbekannter Download-`mode` (erlaubt: `original`, `pdf-original`, `pdf-modified`, `original-modified`)
`rate-limited`	429	Ratenbegrenzung — die Meldung nennt die Wartezeit

Download-Berechtigung (HTTP 403)

Code	Bedeutung
`download-not-permitted`	Download-Stufe der Rolle ist „Kein Download“
`download-redacted-only`	Nur bearbeiteter (geschwärzter) Download erlaubt
`download-original-format-unavailable`	Originalformat ist mit dieser Berechtigung nicht verfügbar (Stufe „Nur PDF“)

Lizenz (HTTP 403)

Code	Bedeutung
`license_missing`	Keine Lizenz hinterlegt — Mandant ist gesperrt (nur Login/Logout und Lizenzseite bleiben erreichbar)
`license_invalid`	Lizenz-Signatur ungültig oder Lizenzstring beschädigt
`license_wrong_hardware`	Lizenz gehört zu anderer Hardware bzw. anderem Mandanten
`license_expired`	Lizenz abgelaufen
`license_user_limit`	Benutzeranlage/-reaktivierung überschreitet die lizenzierte Benutzerzahl
`license_page_quota`	Seitenkontingent erschöpft — neue verwertbare Fassungen werden verweigert (Uploads und Original-Downloads bleiben möglich)
`feature_not_licensed`	Funktion (Schwärzung bzw. Pseudonymisierung) ist nicht lizenziert

Upload-Ablehnungen

Beim Sammel-Upload (POST /api/documents/bulk) bricht ein Einzelfehler den Lauf nicht ab; die Antwort listet betroffene Dateien unter failed[] mit reason:

`reason`	Bedeutung
`read-failed`	Datei konnte nicht gelesen werden
`magic-byte-mismatch`	Dateiinhalt passt nicht zur Dateiendung
`office-sanitizer`	Ablehnung durch die Office-Prüfung (siehe unten)
`create-failed`	Anlage des Dokuments fehlgeschlagen

Gründe der Office-Prüfung (Auszug der Meldungen): „Dokument enthält Makros.“ (immer abgelehnt) · „Dokument enthält externe Referenzen oder OLE-Objekte.“ (nur wenn das Projekt sie nicht erlaubt) · „Archiv hat zu viele Einträge.“ · „Unerlaubter Pfad im Archiv.“ · „Dekomprimierte Größe übersteigt das Limit.“ · „Kompressions-Ratio verdächtig hoch.“ (Schutz vor Zip-Bomben).

Hintergrund-Aufträge (`errorCode`)

Export-, Analyse- und Reidentifizierungs-Aufträge melden Fehler über ein errorCode-Feld, z. B.:

errorCode	Meldung (deutsch)
`Api.Error.Job.TenantNotLicensed`	„Für diesen Mandanten liegt keine gültige Lizenz vor.“
`Api.Error.Job.FeatureNotLicensed`	„Diese Funktion ist in Ihrer Lizenz nicht enthalten.“
`Api.Error.Job.LicensePageQuota`	„Das Seitenkontingent Ihrer Lizenz ist aufgebraucht: …“
`Api.Error.Job.NoDocumentsExported`	„Keine Dokumente exportiert (… übersprungen, … fehlgeschlagen).“
`Api.Error.Job.ExportFailed` / `…WithDetails`	„Export fehlgeschlagen(: …)“
`Api.Error.Job.Interrupted…`	„Durch einen Dienst-Neustart unterbrochen — bitte … erneut starten.“
`Api.Error.Reidentify.FormatUnsupported`	„Format ‚…’ wird für die Re-Identifizierung nicht unterstützt. …“
`Api.Error.Reidentify.NoAliasesFound`	„Im hochgeladenen PDF wurden keine Aliase aus dem Wörterbuch gefunden.“
`Api.Error.Reidentify.MappingFileEmpty`	„Die Mapping-Datei enthält keine gültigen Original/Pseudonym-Zuordnungen.“

Verarbeitungsstatus von Dokumenten

Jede Dokumentversion durchläuft Pending → Processing → Completed bzw. endet mit Failed. Bei Failed nennt das Feld processingError die Ursache (englischer Text). Zwei Werte sind stabil und werden von der Oberfläche gesondert behandelt:

Text	Bedeutung
`Document is password-protected`	Kennwortgeschütztes Dokument — Kennwort über die Fehlerliste der Projektansicht nachreichen
`Document password is incorrect`	Angegebenes Kennwort ist falsch

HTTP-Statuscodes

200/201/204 Erfolg · 400 ungültige Eingabe · 401 Authentifizierung fehlt/ungültig · 403 keine Berechtigung · 404 nicht gefunden · 409 Konflikt (z. B. Kürzel vergeben) · 413 Datei zu groß · 415 Dateityp/Inhalt nicht zulässig · 422 inhaltliche Ablehnung (z. B. Captcha, Office-Prüfung) · 423 Dokument ist durch einen anderen Benutzer ausgecheckt · 429 Ratenbegrenzung.