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) 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://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.

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