Fehlercodes der Documents Partner API

Jede fehlerhafte Antwort der Schnittstelle trägt einen stabilen Fehlercode. Er ist der Teil der Antwort, gegen den eine Integration programmieren sollte – nicht der Meldungstext.

Der Aufbau einer Fehlerantwort

{
  "error": {
    "code": "CONNECTOR_OFFLINE",
    "message": "The customer's connector is not currently connected; retry.",
    "correlationId": "9f3a2b7c4d1e5081",
    "supportCode": "STP-DMS-502-CONN-OFFLINE-9f3a2b7c",
    "details": null,
    "retryAfter": null
  }
}
Feld Bedeutung
code Der stabile Fehlercode. Hierauf programmieren.
message Erläuternder Text. Kann sich jederzeit ändern – nicht auswerten.
correlationId Die Korrelationskennung. Entspricht dem mitgeschickten X-Correlation-Id, sonst neu erzeugt.
supportCode Der Code, den der Support benötigt, um den Aufruf wiederzufinden. Bei Rückfragen immer mitgeben.
details Reserviert für strukturierte Zusatzangaben. Derzeit immer null – die Begründung steht in message.
retryAfter Wartezeit in Sekunden vor dem nächsten Versuch. Steht bei 429 und 503 zusätzlich als Retry-After-Kopfzeile in der Antwort.

Der Support-Code

Er ist so aufgebaut, dass die Kategorie schon beim Lesen erkennbar ist:

STP-DMS-{HTTP-Status}-{Kurzcode}-{Anfang der Vorgangskennung}

Beispiel: STP-DMS-502-CONN-OFFLINE-9f3a2b7c

Eine Partneranwendung sollte ihn an den Endanwender durchreichen. Damit hat der STP Support genau eine Kennung, mit der er den Aufruf in Protokollen und Ablaufaufzeichnungen findet.

Wiederholungsverhalten

Jeder Code trägt eine von zwei Empfehlungen:

Symbol Bedeutung
🔁 Wiederholen – vorübergehende Störung. Mit demselben Idempotency-Key und ansteigender Wartezeit erneut versuchen.
⛔ Nicht wiederholen – dauerhaft. Erst die Anfrage oder die Konfiguration korrigieren.

Einzelheiten dazu stehen in Idempotenz und Wiederholungen.

Der 401 ist die eine Ausnahme. Fehlt das Token, ist es abgelaufen oder ist die Signatur ungültig, antwortet die Schnittstelle mit einem nackten 401 ohne Fehlerumschlag – also ohne code, ohne supportCode und ohne Vorgangskennung. Die Zurückweisung erfolgt, bevor die Fehlerbehandlung überhaupt greift. Eine Integration darf beim 401 deshalb keinen Antwortkörper erwarten; der Statuscode allein ist die Aussage, und die Reaktion darauf ist immer dieselbe: neues Token holen.

Anmeldung und Berechtigung

Code Status Bedeutung
(kein Code) 401 ⛔ Token fehlt, ist abgelaufen oder die Signatur ist ungültig. Antwortet ohne Fehlerumschlag – siehe Kasten oben. Neues Token holen und den Aufruf als neuen Versuch werten.
INSUFFICIENT_SCOPE 403 ⛔ Das Token ist gültig, trägt aber nicht den Scope, den dieser Endpunkt verlangt.
TENANT_MISMATCH 403 ⛔ Der Aufruf zielt auf einen Mandanten, für den der Aufrufer nicht berechtigt ist. Tritt auch auf, wenn ein Ablageschlüssel eines fremden Mandanten verwendet wird.
LICENSE_MISSING 403 ⛔ Der Mandant hat keine Lizenz für die Schnittstelle, oder das Token trägt keinen Lizenzbereich.
CLIENT_NOT_LICENSED 403 ⛔ Der partnergebundene Lizenzbereich im Token wurde für eine andere Anwendung ausgestellt.
SERVICE_USER_SUSPENDED 403 ⛔ Der Dienstbenutzer wurde vom Administrator der Kanzlei gesperrt.
TENANT_INACTIVE 403 ⛔ Der Mandant ist stillgelegt oder die Lizenz ist abgelaufen.
CONNECTOR_DEACTIVATED 403 ⛔ Der Administrator der Kanzlei hat den Connector abgeschaltet. Das ist keine Störung der Plattform.
ON_PREM_PERMISSION_DENIED 403 ⛔ Das lokale Dokumentenmanagement hat die Aktion für den anfragenden Benutzer abgelehnt.
MISSING_USER_IDENTITY 403 ⛔ Das Token trägt keine Benutzerkennung, in deren Namen im Dokumentenmanagement gehandelt werden könnte. Fast immer ein Token aus einem Ablauf ohne Benutzeranmeldung – siehe Erste Schritte.

Prüfung der Anfrage

Code Status Bedeutung
VALIDATION_FAILED 400 ⛔ Die Anfrage entspricht nicht dem erwarteten Aufbau. Welches Feld betroffen ist, steht in message.
ILLEGAL_FILENAME 400 ⛔ Der Dateiname verstößt gegen die Namensregeln des Dokumentenmanagements.
UPLOAD_INTEGRITY_FAILED 400 ⛔ Die abgelegte Datei stimmt nicht mit der zugesicherten Prüfsumme oder Länge überein. Den Upload vollständig wiederholen.
UNSUPPORTED_MEDIA_TYPE 415 ⛔ Die Dateiendung ist nicht zugelassen.
NOT_FOUND 404 ⛔ Die angeforderte Ressource existiert nicht.
MATTER_NOT_FOUND 404 ⛔ Die Suche nach der Akte bzw. dem Ordner lieferte kein Ergebnis.
MATTER_AMBIGUOUS 409 ⛔ Der Name passt auf mehrere Akten bzw. Ordner. Stattdessen über das Aktenzeichen oder die Kennung suchen.
REGISTER_NOT_FOUND 422 ⛔ Das angegebene Register existiert in dieser Akte bzw. diesem Ordner nicht.
INTEGRITY_FAILED 422 🔁 Prüfsummenfehler auf dem Weg zwischen Cloud und Connector. Vollständig wiederholen.
CONFLICT 409 ⛔ Die Aktion widerspricht dem aktuellen Zustand des Objekts – ein Dokument gehört zu genau einer Akte bzw. einem Ordner und wird nicht stillschweigend verschoben.

Idempotenz

Code Status Bedeutung
IDEMPOTENCY_KEY_REUSED 409 ⛔ Der Schlüssel gehört zu einer Anfrage, die bereits abgeschlossen oder gescheitert ist. Es wird kein Ergebnis nachgeliefert – stattdessen den Zustand über die Vorgangsabfrage klären.
IDEMPOTENCY_KEY_INFLIGHT_TIMEOUT 504 🔁 Eine noch laufende Anfrage mit demselben Schlüssel wurde nicht rechtzeitig fertig. Später erneut versuchen.

Begrenzungen und Kontingente

Code Status Bedeutung
RATE_LIMIT_EXCEEDED 429 🔁 Zu viele Anfragen. Retry-After beachten.
PARTNER_CONCURRENCY_LIMIT 429 🔁 Zu viele gleichzeitig laufende Aufträge.
TENANT_BANDWIDTH_LIMIT 429 🔁 Eine Volumengrenze des Mandanten ist erreicht. Ob und welche für Ihre Kanzlei gilt, regelt der Vertrag mit STP.
QUOTA_EXCEEDED 429 ⛔ Ein hartes Nutzungslimit der Lizenz ist erreicht. Wiederholen hilft nicht; welche Grenzen gelten, regelt der Vertrag der Kanzlei mit STP.
TENANT_OVERLOADED 503 🔁 Die Kapazität auf Kanzleiseite ist erschöpft. Retry-After beachten, Vorgabewert 120 Sekunden.

Störungen der Plattform und der Gegenstelle

Code Status Bedeutung
CONNECTOR_OFFLINE 502 🔁 Der Connector der Kanzlei ist nicht verbunden. Bei anhaltendem Auftreten den Administrator der Kanzlei einbinden.
CONNECTOR_ERROR 502 🔁 Der Connector hat die Anfrage erhalten, konnte sie aber nicht abschließen.
CONNECTOR_DECRYPT_FAILED 502 ⛔ Der Connector konnte die Anfrage nicht entschlüsseln – sein Empfangsschlüssel passt nicht. Anders als bei den übrigen 502-Störungen hilft Wiederholen hier nicht, das bleibt so, bis die Schlüsseleinrichtung korrigiert ist. Ein Fall für den STP-Support.
IOT_UNAVAILABLE 502 🔁 Der Nachrichtenvermittler ist nicht erreichbar.
IOT_THROTTLED 502 🔁 Der Nachrichtenvermittler hat gedrosselt.
IOT_PUBLISH_FAILED 502 🔁 Der Auftrag konnte auch nach Wiederholungen nicht zugestellt werden.
STORAGE_UNAVAILABLE 502 🔁 Der Objektspeicher meldet Fehler.
IMPORT_TIMEOUT 504 🔁 Der Import ins Dokumentenmanagement wurde nicht rechtzeitig fertig.
IMPORT_FAILED 502 🔁 Der Import meldete eine vorübergehende Störung.
TARGET_DMS_FAILURE 502 🔁 Das lokale Dokumentenmanagement meldete einen Fehler, der keine Rechteverweigerung ist.
TARGET_DMS_INTEGRITY_FAILED 502 ⛔ Das Dokumentenmanagement meldet eine interne Speicherstörung. Untersuchung auf Kanzleiseite nötig.
LICENSE_SERVICE_UNAVAILABLE 503 🔁 Der Lizenzdienst ist nicht erreichbar.
IAM_UNAVAILABLE 503 🔁 Die STP-Anmeldung ist nicht erreichbar.
KMS_UNAVAILABLE 503 🔁 Der Schlüsseldienst ist nicht erreichbar.
SERVICE_UNAVAILABLE 503 🔁 Die Schnittstelle fährt gerade herunter, etwa bei einer Aktualisierung. Ein Wiederholungsversuch landet auf einer anderen Instanz.
KMS_KEY_NOT_FOUND 502 ⛔ Der Schlüssel des Mandanten ist nicht mehr verfügbar. Fall für den STP-Support.
KMS_ACCESS_DENIED 502 ⛔ Die Cloud hat keinen Zugriff auf den Schlüssel des Mandanten. Fall für den STP-Support.

Interne Störungen

Einige Störungen lösen bei STP intern eine Sicherheits- oder Betriebsmeldung aus. Ihre internen Bezeichnungen verlassen die Plattform bewusst nicht; nach außen erscheint stattdessen immer IMPORT_FAILED – ein Code aus der Tabelle oben, mit der dort genannten Wiederholungsempfehlung.

Für eine Partneranwendung ändert das nichts: Sie behandelt den Code, den sie bekommt, nach der Tabelle oben. Wiederholt sich ein solcher Fehler, hilft der Support-Code weiter.

Umgang mit unbekannten Codes

Neue Codes dürfen innerhalb einer Hauptversion hinzukommen. Eine Integration muss einen unbekannten Code deshalb verkraften, ohne abzustürzen. Die belastbare Rückfallregel ist der HTTP-Status:

Status Verhalten
4xx außer 408, 425, 429 Nicht wiederholen
408, 425, 429 Wiederholen, Retry-After beachten
5xx Wiederholen mit ansteigender Wartezeit

Ist der Code bekannt, gilt seine Empfehlung aus den Tabellen oben – nicht diese Rückfallregel. Deshalb steht bei INTEGRITY_FAILED ein 🔁, obwohl es ein 422 ist: Der Fehler entsteht auf dem Übertragungsweg und verschwindet beim nächsten Versuch. Die Rückfallregel greift nur für Codes, die eine Integration noch nicht kennt.

Näheres in Versionierung und Abkündigung.

Weiterführend