Zum Hauptinhalt springen
Version: FIT-Connect_v1

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-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.
  • 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#

type des technischen FehlersTitel laut httpstatus.esBeschreibung
https://schema.fitko.de/fit-connect/submission-api/problems/constraint-violation400 Bad Request
https://schema.fitko.de/fit-connect/submission-api/problems/request-binding-error400 Bad Request
https://schema.fitko.de/fit-connect/submission-api/problems/no-handler-found404 Not Found
https://schema.fitko.de/fit-connect/submission-api/problems/missing-request-part400 Bad Request
https://schema.fitko.de/fit-connect/submission-api/problems/missing-request-parameter400 Bad Request
https://schema.fitko.de/fit-connect/submission-api/problems/socket-timeout504 Gateway Timeout
https://schema.fitko.de/fit-connect/submission-api/problems/type-mismatch400 Bad Request
https://schema.fitko.de/fit-connect/submission-api/problems/multipart-error400 Bad Request
https://schema.fitko.de/fit-connect/submission-api/problems/message-not-readable400 Bad Request
https://schema.fitko.de/fit-connect/submission-api/problems/method-not-supported405 Method Not Allowed
https://schema.fitko.de/fit-connect/submission-api/problems/media-type-not-supported415 Unsupported Media Type
https://schema.fitko.de/fit-connect/submission-api/problems/media-type-not-acceptable406 Not Acceptable
https://schema.fitko.de/fit-connect/submission-api/problems/unsupported-operation501 Not Implemented
https://schema.fitko.de/fit-connect/submission-api/problems/invalid-state-transition500 Internal Server Error

Fachliche Fehler#

type des fachlichen FehlersTitel laut httpstatus.esBeschreibung
https://schema.fitko.de/fit-connect/submission-api/problems/access-forbidden403 Forbidden
https://schema.fitko.de/fit-connect/submission-api/problems/submission-already-fetched410 Gone
https://schema.fitko.de/fit-connect/submission-api/problems/submission-incomplete422 Unprocessable Entity
https://schema.fitko.de/fit-connect/submission-api/problems/submission-not-found404 Not Found
https://schema.fitko.de/fit-connect/submission-api/problems/not-in-acknowledgeable-state422 Unprocessable Entity
https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-announced422 Unprocessable Entity
https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-found404 Not Found
https://schema.fitko.de/fit-connect/submission-api/problems/destination-not-found404 Not Found
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 Request
https://schema.fitko.de/fit-connect/submission-api/problems/jwk-not-valid422 Unprocessable EntityJWK fachlich nicht zulässig. Details stehen im Feld detail.

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."