docs: "Fehlerverhalten und Statuscodes" ergänzt

docs/5_Fehlerverhalten_und_Statuscodes.md

+# Fehlerverhalten und Statuscodes
+
+> Wo 200 Licht ist, ist auch 403 Schatten. -Göthe
+
+Diese Seite gibt einen Überblick über Fehlerhandling in der XFall RESTful 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)](https://datatracker.ietf.org/doc/html/rfc7231#section-6)
+  zurück.
+* Liefert Fehler (4xx und 5xx HTTP Statuscodes) im JSON Format
+  nach [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807) aus.
+    * Fehler besitzen **immer** folgende Felder:
+        * `type`: Eine URI (möglicherweise als Website aufrufbar) die den Typ des Fehlers eindeutig klassifiziert.
+          Beispiel: `https://fitko.uber.space/problem/application-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](https://git.fitko.de/fit-connect/FIT-Connect-PoC/-/issues/new).
+
+Wir unterscheiden zwischen technischen und fachlichen Fehlern. Technische Fehler sind nicht explizit in der API-Spec
+abgebildet. Fachliche schon.
+
+### Technische Fehler
+
+| `type` des technischen Fehlers                                | Titel laut [httpstatus.es](https://httpstatuses.com/)   | Beschreibung |
+|---------------------------------------------------------------|---------------------------------------------------------|--------------|
+| https://fitko.uber.space/problem/constraint-violation         | 400 Bad Request                                         |              |
+| https://fitko.uber.space/problem/request-binding-error        | 400 Bad Request                                         |              |
+| https://fitko.uber.space/problem/no-handler-found             | 404 Not Found                                           |              |
+| https://fitko.uber.space/problem/missing-request-part         | 400 Bad Request                                         |              |
+| https://fitko.uber.space/problem/missing-request-parameter    | 400 Bad Request                                         |              |
+| https://fitko.uber.space/problem/socket-timeout               | 504 Gateway Timeout                                     |              |
+| https://fitko.uber.space/problem/type-mismatch                | 400 Bad Request                                         |              |
+| https://fitko.uber.space/problem/multipart-error              | 400 Bad Request                                         |              |
+| https://fitko.uber.space/problem/message-not-readable         | 400 Bad Request                                         |              |
+| https://fitko.uber.space/problem/method-not-supported         | 405 Method Not Allowed                                  |              |
+| https://fitko.uber.space/problem/media-type-not-supported     | 415 Unsupported Media Type                              |              |
+| https://fitko.uber.space/problem/media-type-not-acceptable    | 406 Not Acceptable                                      |              |
+| https://fitko.uber.space/problem/unsupported-operation        | 501 Not Implemented                                     |              |
+| https://fitko.uber.space/problem/invalid-state-transition     | 500 Internal Server Error                               |              |
+
+### Fachliche Fehler
+
+| `type` des fachlichen Fehlers                                 | Titel laut [httpstatus.es](https://httpstatuses.com/)   | Beschreibung |
+|---------------------------------------------------------------|---------------------------------------------------------|--------------|
+| https://fitko.uber.space/problem/access-forbidden             | 403 Forbidden                                           |              |
+| https://fitko.uber.space/problem/application-already-fetched  | 410 Gone                                                |              |
+| https://fitko.uber.space/problem/application-incomplete       | 422 Unprocessable Entity                                |              |
+| https://fitko.uber.space/problem/application-not-found        | 404 Not Found                                           |              |
+| https://fitko.uber.space/problem/not-in-acknowledgeable-state | 422 Unprocessable Entity                                |              |
+| https://fitko.uber.space/problem/attachment-not-announced     | 422 Unprocessable Entity                                |              |
+| https://fitko.uber.space/problem/attachment-not-found         | 404 Not Found                                           |              |
+| https://fitko.uber.space/problem/destination-not-found        | 404 Not Found                                           |              |
+| https://fitko.uber.space/problem/empty-attachment             | 400 Bad Request                                         |              |
+
+## 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."