Zum Hauptinhalt springen

Fehlerverhalten und Statuscodes

Wo 200 Licht ist, ist auch 403 Schatten. -Göthe

Diese Seite gibt einen Überblick über die Fehlerarten in der FIT-Connect Submission API (API).

In diesem Kontext sei auch die Fehlerliste der für SETs zu erwähnen.

Features

  • Liefert zu allen Fehlerantworten einen HTTP Statuscode laut RFC 7231 (Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content) zurück.
  • Liefert Fehler (4xx und 5xx HTTP Statuscodes) im JSON Format nach RFC 7807 (Problem Details for HTTP APIs) aus.
    • Fehler besitzen immer folgende Felder:
      • type: Eine URI (möglicherweise als Website aufrufbar) die den Typ des Fehlers eindeutig klassifiziert. Beispiel: https://schema.fitko.de/fit-connect/submission-api/problems/submission-not-found
      • title: Ein kurzer und menschenlesbarer Titel des Fehlers. Beispiel: Application not found
      • status: Eine Kopie des HTTP Statuscodes
    • Fehler können optional weitere Felder beinhalten. API Clients müssen hiermit umgehen können.

Liste von Fehlercodes

Wir versuchen bei Fehlern stets sinnvolle Fehlermeldungen bereitzustellen um eine Fehleranalyse zu vereinfachen. Wir sind aber auch Menschen und daher nicht perfekt. Falls euch ein Fehler oder eine Inkonsistenz auffällt, erstellt bitte ein Issue.

type des fachlichen FehlersTitel laut httpstatus.esBeschreibung
https://schema.fitko.de/fit-connect/submission-api/problems/attachment-already-announced422 Unprocessable EntityDie im announcedAttachments übermittelten UUIDs wurden bereits an anderer Stelle verwendet. Dies ist nicht zulässig, da die IDs global eindeutig sein müssen.
https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-announced422 Unprocessable EntityDie Anlage muss vor dem übermitteln in der Einreichung / Antwort angekündigt werden.
https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-found404 Not FoundDie angefragte Anlage konnte nicht gefunden werden.
https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-not-found422 Unprocessable EntityIm übermittelten Ereignis befinden sich keine authenticationTags.
https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-processing422 Unprocessable EntityDas übermittelte Ereignis ist nicht format-konform, sodass sich keine authenticationTags bestimmen lassen.
https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-validation422 Unprocessable EntityDie übermittelten authenticationTags stimmen nicht mit denen der Einreichung überein.
https://schema.fitko.de/fit-connect/submission-api/problems/callback-creation-exception422 Unprocessable EntityDie übermittelte Callback-URL ist ungültig.
https://schema.fitko.de/fit-connect/submission-api/problems/case-not-found404 Not FoundDer Vorgang konnte nicht gefunden werden.
https://schema.fitko.de/fit-connect/submission-api/problems/destination-not-found404 Not FoundDer Zustellpunkt konnte nicht gefunden werden.
https://schema.fitko.de/fit-connect/submission-api/problems/destination-state-invalid422 Unprocessable EntityDer Zustellpunkt existiert, hat aber einen für die Aktion unzulässigen Status.
https://schema.fitko.de/fit-connect/submission-api/problems/empty-attachment400 Bad RequestDie übermittelte Anlage ist leer.
https://schema.fitko.de/fit-connect/submission-api/problems/encryption-public-key-id-does-not-match-encryptionkid400 Bad RequestBeim Erstellen eines neuen Zustellpunktes stimmt die encryptionKid nicht mit der Key Id des übermittelten Verschlüsselungs Public Key encryptionPublicKey überein.
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-jwe400 Bad RequestDer verschlüsselte Datensatz ist invalide. Details sind der Antwort zu entnehmen.
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-jwe-content400 Bad RequestEs besteht ein Problem mit dem verschlüsselten Inhalt in den Authentication Tags.
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-path-parameter400 Bad RequestUngültiger Parameter im Anfragepfad. Details sind der Antwort zu entnehmen.
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-reply-modification400 Bad RequestDie angestrebte Modifikation der Antwort ist nicht erlaubt. Details sind der Antwort zu entnehmen.
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-set-schema-uri422 Unprocessable EntityDie im übermittelten Ereignis angegebene URI für das SET-Schema ist ungültig.
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-state-transition500 Internal Server ErrorDie Ressource ist nicht im korrekten Status / hat unzureichende Vorbedingungen für einen Statusübergang.
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-subject-claim403 ForbiddenDer Abruf dieser Resource ist nur mit dem passenden Client (Token sub claim) möglich.
https://schema.fitko.de/fit-connect/submission-api/problems/key-for-destination-encryption-kid-not-found400 Bad RequestBeim Aktualisieren der encryptionKid eines Zustellpunktes wurde der gewünschte Verschlüsselungs Public Key nicht für den Zustellpunkt hinterlegt gefunden. Der Key muss dem Zustellpunkt hinterlegt werden.
https://schema.fitko.de/fit-connect/submission-api/problems/key-for-destination-not-found404 Not FoundFür den Zustellpunkt kann der angeforderte Public Key nicht gefunden werden.
https://schema.fitko.de/fit-connect/submission-api/problems/overwriting-non-identical-reply-channels409 ConflictEin Setzen der Reply Channels würde die in den Verwaltungsleistungen (services.*.replyChannels) überschreiben.
https://schema.fitko.de/fit-connect/submission-api/problems/public-key-already-exists400 Bad RequestBeim Erstellen eines Zustellpunktes oder beim Hochladen eines neuen Public Keys für einen Zustellpunkt wird ein Public Key verwendet, der eine Key Id besitzt, die im Zustellpunkt schon hinterlegt wurde, aber einen anderen Key Inhalt besitzt. Verwenden Sie bitte eine andere Key Id.
https://schema.fitko.de/fit-connect/submission-api/problems/public-key-does-not-support-purpose400 Bad RequestBeim Erstellen oder Aktualisieren eines Zustellpunktes verwendete Public Keys können nicht für den dafür vorgesehenen Zweck verwendet werden. Verwenden Sie nur Public Keys mit dem richtigen Zweck (z.B. "verify" für Signatur, "wrapKey" fürs Verschlüsseln).
https://schema.fitko.de/fit-connect/submission-api/problems/public-key-invalid-exception422 Unprocessable EntityDer öffentliche Schlüssel eines Zustellpunkts ist ungültig.
https://schema.fitko.de/fit-connect/submission-api/problems/public-key-not-found404 Not FoundBeim Hinterlegen eines Ereignisses ins Ereignisprotokoll konnte der Public Key nicht gefunden werden, der nötig gewesen wäre, um die Ereignis-Signatur validieren zu können. Der Key muss beim Zustellpunkt hinterlegt werden.
https://schema.fitko.de/fit-connect/submission-api/problems/reply-incomplete422 Unprocessable EntityDie Antwort ist noch nicht vollständig. Beispielsweise wurden noch nicht alle angekündigten Anhänge hochgeladen.
https://schema.fitko.de/fit-connect/submission-api/problems/reply-not-found404 Not FoundDie Antwort konnte nicht gefunden werden.
https://schema.fitko.de/fit-connect/submission-api/problems/security-event-token-validation422 Unprocessable EntityDas übermittelte Security Event Token ist fachlich nicht zulässig. Details stehen im Feld issue.
https://schema.fitko.de/fit-connect/submission-api/problems/service-not-supported422 Unprocessable EntityDie Verwaltungsleistung der Einreichung wird vom Zustellpunkt nicht unterstützt.
https://schema.fitko.de/fit-connect/submission-api/problems/set-schema-invalid400 Bad RequestEin Ereignis ist nicht schema-konform.
https://schema.fitko.de/fit-connect/submission-api/problems/set-schema-not-found404 Not FoundDie Schema-URL eines Ereignisses ist syntaktisch gültig, aber semantisch ungültig.
https://schema.fitko.de/fit-connect/submission-api/problems/submission-incomplete422 Unprocessable EntityDie Einreichung ist noch nicht vollständig. Beispielsweise wurden noch nicht alle angekündigten Anhänge hochgeladen.
https://schema.fitko.de/fit-connect/submission-api/problems/submission-not-found404 Not FoundDie Einreichung konnte nicht gefunden werden.

Nicht alle möglichen Fehler (v.a. technische Fehler) sind hier abgebildet. Diese besitzen allerdings ebenfalls die gleichen Felder und sollten von einem Client entsprechend behandelt werden.

Verhalten von API Clients

API-Clients sollten gemäß RFC 7231 so implementiert sein, dass auch unbekannte HTTP Statuscodes gemäß ihrer Statusklasse (Axx, A=[1,5]) interpretiert werden können:

"HTTP status codes are extensible. HTTP clients are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, a client MUST understand the class of any status code, as indicated by the first digit, and treat an unrecognized status code as being equivalent to the x00 status code of that class, with the exception that a recipient MUST NOT cache a response with an unrecognized status code."

Quelle: RFC 7231, section 6: Response Status Codes