Eine vage Fehlermeldung hilft niemandem, weder dem Nutzer noch dem Entwickler auf der anderen Seite.
Wenn eine API schlechte Fehlermeldungen produziert, muss der Client-Entwickler Fehlerpfade durch Ausprobieren verstehen. Das kostet Zeit, erzeugt Frustration, und fuehrt am Ende zu Client-Implementierungen, die Fehlerbehandlung schlicht weglassen, weil sie sowieso nicht weiterhilft.
Gutes Fehlerhandling ist ein Teil der Developer Experience.
RFC 7807, der Standard fuer Problem Details
Eine Fehler-Response nach diesem Standard enthaelt Type, Title, Status, Detail, Instance und optionale strukturierte Feldfehler, maschinenlesbar, menschenlesbar und erweiterbar zugleich.
HTTP Status Codes richtig einsetzen
200 fuer Erfolg, 201 fuer erstellte Ressourcen, 204 fuer Erfolg ohne Response-Body, 400 fuer fehlerhafte Client-Eingaben, 401 fuer fehlende Authentifizierung, 403 fuer fehlende Autorisierung, 404 fuer nicht gefundene Ressourcen, 422 fuer Validierungsfehler, 429 fuer ueberschrittene Rate Limits, 500 fuer Serverfehler. Was man vermeiden sollte: 200 fuer Fehler zurueckzugeben und den eigentlichen Status im Body zu verstecken, das bricht HTTP-Semantik und verwirrt jeden Client.
Fehlercodes als Vertrag
Zusaetzlich zum HTTP-Status ermoeglichen anwendungsspezifische Fehlercodes dem Client, gezielt auf bestimmte Situationen zu reagieren, deutlich informativer als der Status Code allein.
Checkliste: RFC 7807 als Standard implementiert, HTTP Status Codes semantisch korrekt verwendet, anwendungsspezifische Fehlercodes dokumentiert, Validierungsfehler mit Feldnamen zurueckgegeben, keine sensiblen Informationen in Fehler-Responses, Server-Fehler geloggt statt an den Client zurueckgegeben.
Ein Beispiel aus der Praxis
Eine API gab bei praktisch jedem Fehler denselben generischen Text „Ein Fehler ist aufgetreten“ zurueck, unabhaengig davon, ob eine Pflichtangabe fehlte, die Authentifizierung ungueltig war oder ein interner Serverfehler vorlag. Partnerentwickler mussten daraufhin jeden Fehlerfall durch Ausprobieren rekonstruieren. Nach der Umstellung auf strukturierte, nach RFC 7807 formatierte Fehlerantworten mit konkreten Feldangaben sank die Zahl der Supportanfragen zu Integrationsproblemen binnen weniger Wochen deutlich.
API-Fehlerhandling ueberarbeiten? markom.digital verbessert API-Fehlerhandling, von der Spezifikation bis zur Implementierung.
