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

Hinweis

Einzelne ältere Endpunkte liefern das code-Feld noch nicht; dort erscheint vorerst nur ein englischer error-Text.

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.