Schnittstellen

Fehlerhandling in Schnittstellenentwicklung: Checkliste, typische Fehler, Best Practices

Fehlerhandling: Problem Details (RFC 7807) & klare Messages.

Fehlerhandling in APIs: Problem Details und klare Fehlercodes

"Something went wrong" hilft niemandem. Nicht dem Nutzer, nicht dem Entwickler.

Warum API-Fehlerhandling so wichtig ist

Wenn eine API schlechte Fehlermeldungen produziert, muss der Client-Entwickler Fehlerpfade durch Ausprobieren verstehen. Das kostet Zeit, erzeugt Frustration, und führt zu schlechten Client-Implementierungen (weil Fehlerhandling weggelassen wird, weil es eh nicht hilft).

Gutes Fehlerhandling ist Teil der Developer Experience.

RFC 7807 – Problem Details

Der Standard für HTTP-API-Fehlermeldungen. Eine Fehler-Response sieht so aus:

{  
  "type": "https://euredomain.de/errors/validation-error",  
  "title": "Validation Error",  
  "status": 422,  
  "detail": "The field 'email' must be a valid email address.",  
  "instance": "/api/users",  
  "errors": [  
    {"field": "email", "message": "Invalid email format"}  
  ]  
}

Maschinenlesbar, menschenlesbar, erweiterbar. Das ist der Standard.

HTTP Status Codes richtig einsetzen

200: Erfolg. 201: Ressource erstellt. 204: Erfolg ohne Response Body. 400: Client-Fehler (ungültige Eingabe). 401: Nicht authentifiziert. 403: Nicht autorisiert (aber authentifiziert). 404: Ressource nicht gefunden. 422: Validierungsfehler. 429: Rate Limit überschritten. 500: Server-Fehler.

Bitte nicht: 200 für Fehler zurückgeben und den Status im Body codieren. Das bricht HTTP-Semantik und verwirrt jeden API-Client.

Fehlercodes als Vertrag

Anwendungsspezifische Fehlercodes (zusätzlich zum HTTP Status Code) ermöglichen dem Client, spezifisch auf Fehlersituationen zu reagieren. "code": "USER_NOT_VERIFIED" ist informativer als HTTP 403 allein.

Checkliste Fehlerhandling

RFC 7807 Problem Details als Standard implementiert
HTTP Status Codes semantisch korrekt verwendet
Anwendungsspezifische Fehlercodes dokumentiert
Validierungsfehler mit Feldnamen zurückgegeben
Keine sensiblen Informationen in Fehler-Responses
Server-Fehler geloggt, aber nicht an Client zurückgegeben

API-Fehlerhandling überarbeiten?

markom.digital verbessert API-Fehlerhandling – von der Spezifikation bis zur Implementierung.

Weitere Beiträge