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
  }
}

Diesen Aufbau hat jede Fehlerantwort, die die Schnittstelle selbst erzeugt. Einige wenige Zurückweisungen erfolgen davor – dann kommt der Statuscode ohne Antwortkörper zurück. Einzelheiten stehen im Kasten unter Wiederholungsverhalten.

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:

Einzelheiten dazu stehen in Idempotenz und Wiederholungen.

Zwei Fälle kommen ohne den normalen Fehlerumschlag zurück. Beide werden zurückgewiesen, bevor die eigentliche Fehlerbehandlung der Schnittstelle überhaupt greift:

• 401 – das Token fehlt, ist abgelaufen oder die Signatur ist ungültig. Denselben nackten 401 gibt es auch auf eine Adresse, die es gar nicht gibt: ohne gültiges Token ist von außen nicht zu erkennen, ob ein Endpunkt überhaupt existiert. Die Reaktion ist immer dieselbe: neues Token holen.
• 400 oder 404 auf eine ungewöhnlich geformte Adresse – enthält die Adresse ein Zeichen, das dort nicht zulässig ist, oder einen Bestandteil wie .., wird der Aufruf schon vor der Schnittstelle abgewiesen. Die genaue Antwort (Statuscode und ob überhaupt ein Antwortkörper mitkommt) ist für diesen schmalen Fall nicht Teil des versionierten Vertrags dieser Schnittstelle – anders als bei jedem anderen Fehler oben oder unten in dieser Tabelle sollte eine Integration hier keinen bestimmten code, kein bestimmtes Format und keinen bestimmten Statuscode erwarten. In beiden Fällen die aufgerufene Adresse prüfen. Reguläre Prozentkodierung ist davon nicht betroffen – ein fehlerhafter Wert darin wird ganz normal mit VALIDATION_FAILED samt Fehlerumschlag beantwortet.

Eine Integration darf im 401-Fall keinen Antwortkörper erwarten; der Statuscode allein ist die Aussage.

Anmeldung und Berechtigung

Prüfung der Anfrage

Idempotenz

Begrenzungen und Kontingente

Störungen der Plattform und der Gegenstelle

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:

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

• Idempotenz und Wiederholungen
• Endpunktübersicht