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.
- Fehler besitzen immer folgende Felder:
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 Fehlers | Titel laut httpstatus.es | Beschreibung |
---|---|---|
https://schema.fitko.de/fit-connect/submission-api/problems/attachment-already-announced | 422 Unprocessable Entity | Die 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-announced | 422 Unprocessable Entity | Die Anlage muss vor dem übermitteln in der Einreichung / Antwort angekündigt werden. |
https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-found | 404 Not Found | Die angefragte Anlage konnte nicht gefunden werden. |
https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-not-found | 422 Unprocessable Entity | Im übermittelten Ereignis befinden sich keine authenticationTags . |
https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-processing | 422 Unprocessable Entity | Das übermittelte Ereignis ist nicht format-konform, sodass sich keine authenticationTags bestimmen lassen. |
https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-validation | 422 Unprocessable Entity | Die übermittelten authenticationTags stimmen nicht mit denen der Einreichung überein. |
https://schema.fitko.de/fit-connect/submission-api/problems/callback-creation-exception | 422 Unprocessable Entity | Die übermittelte Callback-URL ist ungültig. |
https://schema.fitko.de/fit-connect/submission-api/problems/case-not-found | 404 Not Found | Der Vorgang konnte nicht gefunden werden. |
https://schema.fitko.de/fit-connect/submission-api/problems/destination-not-found | 404 Not Found | Der Zustellpunkt konnte nicht gefunden werden. |
https://schema.fitko.de/fit-connect/submission-api/problems/destination-state-invalid | 422 Unprocessable Entity | Der Zustellpunkt existiert, hat aber einen für die Aktion unzulässigen Status. |
https://schema.fitko.de/fit-connect/submission-api/problems/empty-attachment | 400 Bad Request | Die übermittelte Anlage ist leer. |
https://schema.fitko.de/fit-connect/submission-api/problems/encryption-public-key-id-does-not-match-encryptionkid | 400 Bad Request | Beim 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-jwe | 400 Bad Request | Der verschlüsselte Datensatz ist invalide. Details sind der Antwort zu entnehmen. |
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-jwe-content | 400 Bad Request | Es besteht ein Problem mit dem verschlüsselten Inhalt in den Authentication Tags. |
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-path-parameter | 400 Bad Request | Ungültiger Parameter im Anfragepfad. Details sind der Antwort zu entnehmen. |
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-reply-modification | 400 Bad Request | Die 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-uri | 422 Unprocessable Entity | Die im übermittelten Ereignis angegebene URI für das SET-Schema ist ungültig. |
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-state-transition | 500 Internal Server Error | Die 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-claim | 403 Forbidden | Der 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-found | 400 Bad Request | Beim 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-found | 404 Not Found | Für den Zustellpunkt kann der angeforderte Public Key nicht gefunden werden. |
https://schema.fitko.de/fit-connect/submission-api/problems/overwriting-non-identical-reply-channels | 409 Conflict | Ein 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-exists | 400 Bad Request | Beim 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-purpose | 400 Bad Request | Beim 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-exception | 422 Unprocessable Entity | Der öffentliche Schlüssel eines Zustellpunkts ist ungültig. |
https://schema.fitko.de/fit-connect/submission-api/problems/public-key-not-found | 404 Not Found | Beim 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-incomplete | 422 Unprocessable Entity | Die 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-found | 404 Not Found | Die Antwort konnte nicht gefunden werden. |
https://schema.fitko.de/fit-connect/submission-api/problems/security-event-token-validation | 422 Unprocessable Entity | Das ü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-supported | 422 Unprocessable Entity | Die Verwaltungsleistung der Einreichung wird vom Zustellpunkt nicht unterstützt. |
https://schema.fitko.de/fit-connect/submission-api/problems/set-schema-invalid | 400 Bad Request | Ein Ereignis ist nicht schema-konform. |
https://schema.fitko.de/fit-connect/submission-api/problems/set-schema-not-found | 404 Not Found | Die Schema-URL eines Ereignisses ist syntaktisch gültig, aber semantisch ungültig. |
https://schema.fitko.de/fit-connect/submission-api/problems/submission-incomplete | 422 Unprocessable Entity | Die 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-found | 404 Not Found | Die 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."