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