Fehlercodes

Jeder Fehler der API ist ein Problem-Details-Objekt nach RFC 9457 mit Content-Type: application/problem+json:

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "not_ready",
  "detail": "Dokument wird noch auf Schadsoftware geprüft — bitte kurz warten.",
  "instance": "/api/v1/documents/6f1c…/download"
}

Feld	Inhalt
status	HTTP-Status, identisch mit dem der Antwort
code	stabiler, maschinenlesbarer Code. Verzweige im Code nur hierauf
detail	menschenlesbare Erklärung (Deutsch). Kann sich ändern, nicht parsen
errors	nur bei validation_error: Liste der Schemaverletzungen (loc, msg, type)
instance	Pfad der fehlgeschlagenen Anfrage

Bestehende Codes ändern in v1 weder Bedeutung noch Schreibweise. Neue Codes können dazukommen. Behandle unbekannte Codes deshalb anhand des HTTP-Status (Versionierung).

Alle Codes

Diese Tabelle wird beim Bauen der Doku direkt aus der openapi.json erzeugt.

Code	HTTP	Bedeutung
bad_request	400	Anfrage fehlerhaft, ohne spezifischeren Code.
validation_error	422	Body, Pfad oder Query verletzt das Schema (Details in errors).
unauthenticated	401	API-Key fehlt, ist unbekannt, abgelaufen oder widerrufen.
plan_required	403	API-Zugang nur mit bezahltem Tarif; Keys sind suspendiert, nicht gelöscht.
insufficient_scope	403	dem API-Key fehlt der für die Route nötige Scope.
forbidden	403	Zugriff verweigert, ohne spezifischeren Code.
not_found	404	Ressource existiert nicht oder gehört einem anderen Konto.
method_not_allowed	405	HTTP-Methode auf dieser Route nicht erlaubt.
conflict	409	Zustand der Ressource lässt die Aktion nicht zu (z. B. kein Entwurf mehr).
not_ready	409	Dokument wird noch geprüft (Malware-Scan) bzw. konvertiert.
scan_infected	409	Dokument wurde als schädlich erkannt und entfernt. (auch als failure_code am Dokument)
scan_failed	409	Malware-Scan endgültig fehlgeschlagen; Datei als neues Dokument hochladen. (auch als failure_code am Dokument)
conversion_failed	409	DOCX-Konvertierung nach PDF fehlgeschlagen. (auch als failure_code am Dokument)
anchor_not_found	422	Anker-Platzhalter ohne passenden Signer, Signer ohne Platzhalter, zu viele (> 20 je Signer) oder zu grosse Platzhalter. (auch als failure_code am Dokument)
anchor_scan_failed	422	PDF für die Anker-Suche abgelehnt (Seitenlimit, Zeit- oder Speicherlimit, zu viele Platzhalter, Platzhalter auf gedrehter Seite, unlesbar, wiederholt abgebrochen, Datei fehlt). (auch als failure_code am Dokument)
quota_exceeded	402	Dokument-Kontingent des Kontos ist ausgeschöpft.
payload_too_large	413	Datei oder Anfrage überschreitet die Grössengrenze.
rate_limited	429	Rate-Limit erreicht; Retry-After nennt die Wartezeit in Sekunden.
idempotency_key_required	400	die Route verlangt einen Idempotency-Key-Header.
idempotency_key_invalid	400	Idempotency-Key ist leer, zu lang (> 255) oder enthält Nicht-ASCII-Zeichen.
idempotency_key_reused	422	derselbe Idempotency-Key wurde mit einer anderen Anfrage (Route oder Body) verwendet.
idempotency_key_in_use	409	eine Anfrage mit diesem Idempotency-Key läuft noch; später erneut versuchen.
webhook_url_rejected	422	Webhook-URL unzulässig: nur https://, Host muss öffentlich auflösen (keine privaten, internen oder Link-Local-Adressen).
test_mode_unavailable	503	der Test-Modus ist auf dieser Umgebung nicht eingerichtet (Test-Zertifikat fehlt oder ist ungültig); später erneut versuchen.
internal_error	500	unerwarteter Serverfehler.

Wie reagieren?

Situation	Codes	Reaktion
Wiederholbar	rate_limited, idempotency_key_in_use, internal_error, 5xx	mit Backoff wiederholen; bei 429 Retry-After abwarten; POST mit demselben Idempotency-Key
Später wiederholbar	not_ready	Dokument wird noch geprüft. Per API-Key wird ohnehin «sobald bereit» versendet, not_ready tritt nur bei Aktionen auf, die ein fertiges Dokument brauchen
Konfiguration	unauthenticated, plan_required, insufficient_scope	Key, Tarif oder Scopes prüfen; nicht automatisch wiederholen
Eingabe	validation_error, bad_request, payload_too_large, anchor_not_found, anchor_scan_failed, webhook_url_rejected, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused	Request korrigieren
Zustand	conflict, not_found	Dokument-Status mit GET /documents/{id} neu laden
Dokument unbrauchbar	scan_infected, scan_failed, conversion_failed	neues Dokument mit korrigierter Datei anlegen
Kontingent	quota_exceeded	per API-Key derzeit nicht ausgelöst (reserviert für künftige Tarife); ein 402 ohne spezifischeren Code erscheint ebenfalls als quota_exceeded

Die Codes scan_infected, scan_failed, conversion_failed, anchor_not_found und anchor_scan_failed erscheinen ausserdem als failure_code am Dokument, wenn ein angeforderter Versand asynchron scheitert (Ablauf & Status).