Fehlerverhalten und Statuscodes
Wo 200 Licht ist, ist auch 403 Schatten. -Göthe
Diese Seite gibt einen Überblick über Fehlerhandling in der FIT-Connect Submission API (nachfolgend nur noch API genannt).
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-foundtitle: Ein kurzer und menschenlesbarer Titel des Fehlers. Beispiel:Application not foundstatus: 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:
- Unterscheidet zwischen technischen und fachlichen Fehlern
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.
Wir unterscheiden zwischen technischen und fachlichen Fehlern. Technische Fehler sind nicht explizit in der API-Spec abgebildet. Fachliche schon.
Technische Fehler
Fachliche Fehler
type des fachlichen Fehlers | Titel laut httpstatus.es | Beschreibung |
|---|---|---|
| https://schema.fitko.de/fit-connect/submission-api/problems/access-forbidden | 403 Forbidden | |
| https://schema.fitko.de/fit-connect/submission-api/problems/submission-already-fetched | 410 Gone | |
| https://schema.fitko.de/fit-connect/submission-api/problems/submission-incomplete | 422 Unprocessable Entity | |
| https://schema.fitko.de/fit-connect/submission-api/problems/submission-not-found | 404 Not Found | |
| https://schema.fitko.de/fit-connect/submission-api/problems/not-in-acknowledgeable-state | 422 Unprocessable Entity | |
| https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-announced | 422 Unprocessable Entity | |
| https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-found | 404 Not Found | |
| https://schema.fitko.de/fit-connect/submission-api/problems/destination-not-found | 404 Not Found | |
| 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/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/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/empty-attachment | 400 Bad Request | |
| https://schema.fitko.de/fit-connect/submission-api/problems/jwk-not-valid | 422 Unprocessable Entity | JWK fachlich nicht zulässig. Details stehen im Feld detail. |
| 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/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/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-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. |
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."