REST API Fehlerbehandlung: Statuscodes und Error Objects

Gute REST API Fehlerbehandlung hilft Entwicklern, Probleme schnell zu verstehen, zu lokalisieren und zu beheben, ohne raten zu müssen.

Kompakte Beschreibung

REST API Fehlerbehandlung beschreibt, wie eine Schnittstelle auf ungültige Anfragen, technische Probleme und fachliche Verletzungen reagiert. Dazu gehören der richtige HTTP-Statuscode, eine strukturierte Fehlerantwort und eine eindeutige Fehleridentifikation. RFC 7807 definiert mit Problem Details ein Standardformat für Fehlerantworten, das Felder wie type, title, status, detail und instance vorsieht. Eine gute Fehlerbehandlung ist konsistent über alle Endpunkte hinweg, enthält ausreichend Informationen für Entwickler und verrät keine sicherheitsrelevanten Interna. Sie reduziert Supportaufwand, verbessert die Developer Experience und ermöglicht es Clients, Fehler automatisch zu klassifizieren und angemessen zu reagieren.

Wenn Du mit APIS arbeitest, dann werden serverseitige Fehler Deine größten Endgegner. Einmal hat ein Anbieter, w.z.B. Langdock seine Token- und Anfragelimits und dann nutzen die auch noch Cloudflare und Cloudflare hat eigene Limits und Regeln. Wenn Deine Anfragen also nur halb ausgewertet werden, oder gefühlt nur sporadisch, dann ist gues Debugging wichtig. Welche Rückmeldung kommt und was bedeutet sie.

Wichtige Komponenten

Richtige HTTP-Statuscodes

HTTP-Statuscodes sind die erste Information, die ein Client über den Erfolg oder Misserfolg einer Anfrage erhält. 4xx Codes zeigen Clientfehler, 5xx Codes Serverfehler. Wichtige 4xx Codes sind 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Content und 429 Too Many Requests. 5xx Codes wie 500 Internal Server Error, 502 Bad Gateway und 503 Service Unavailable weisen auf serverseitige Probleme hin.

Problem Details nach RFC 7807

RFC 7807 definiert ein Standardformat für Fehlerantworten. Ein Problem Detail enthält mindestens type, title, status und detail. Optional können instance für die fehlerhafte URI und weitere Erweiterungen hinzugefügt werden. Der Content-Type ist application/problem+json. Das Format ermöglicht es Clients, Fehler einheitlich zu parsen und darzustellen.

Eindeutige Fehleridentifikatoren

Jede Fehlerantwort sollte eine eindeutige Fehler-ID enthalten, beispielsweise eine UUID oder eine Korrelations-ID. Das ermöglicht es, Fehler in Logs und Monitoring-Systemen nachzuverfolgen, ohne interne Details preiszugeben. Der Client kann die Fehler-ID beim Support angeben.

Fehlerkategorien und Codes

Neben HTTP-Statuscodes sollten Fehlerantworten anwendungsspezifische Fehlercodes enthalten. Ein Code wie ORDER_NOT_FOUND oder PAYMENT_DECLINED ist präziser als ein allgemeiner 404. Diese Codes helfen Clients, gezielt auf bestimmte Situationen zu reagieren.

Validierungsfehler

Bei Validierungsfehlern sollte die Antwort die fehlerhaften Felder nennen und den Grund angeben. Beispielsweise: field: email, message: Ungültiges E-Mail-Format. Das ermöglicht es, Formulare im Client direkt zu korrigieren.

Fehler ohne Interna preiszugeben

Fehlermeldungen sollten ausreichend informativ sein, aber keine internen Pfade, Stacktraces oder Datenbankdetails enthalten. Solche Informationen können Angreifern helfen. Interne Details gehören in Logs, nicht in die API-Antwort.

Lokalisierung und Sprache

Fehlermeldungen können sprachabhängig sein. Der Client sollte über den Accept-Language Header mitteilen, welche Sprache er erwartet. Der Server antwortet dann mit entsprechend lokalisierten Meldungen, sofern verfügbar.

Retry-Informationen

Bei vorübergehenden Fehlern wie 429 oder 503 sollte der Server über den Retry-After Header mitteilen, wann der Client die Anfrage wiederholen kann. Das verhindert unüberlegte Wiederholungen und reduziert die Serverlast.

Logging und Monitoring

Jeder Fehler sollte serverseitig mit Kontext geloggt werden, inklusive Request-ID, Zeitstempel, Endpunkt, Statuscode und Fehlerdetails. Monitoring-Systeme können darauf aufbauend Alerts auslösen und Fehlertrends erkennen.

Konsistenz über alle Endpunkte

Alle Endpunkte einer API sollten dasselbe Fehlerformat verwenden. Eine einheitliche Struktur erleichtert die Client-Implementierung und die Fehlerbehandlung. Abweichungen führen zu unnötigem Sondercode und erhöhtem Fehlerpotenzial.

Praxisbeispiel

Ein Client sendet eine Anfrage zur Erstellung einer Bestellung mit ungültigen Daten:

POST /api/v1/orders
Content-Type: application/json

{
  "customerId": 123,
  "items": [
    { "productId": 42, "quantity": 0 }
  ]
}

Die API antwortet mit 422 Unprocessable Content und einem Problem Detail:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "type": "https://api.shop.de/problems/validation-error",
  "title": "Validierungsfehler",
  "status": 422,
  "detail": "Die Bestellung enthält ungültige Daten.",
  "instance": "/api/v1/orders",
  "errors": [
    {
      "field": "items[0].quantity",
      "code": "QUANTITY_TOO_LOW",
      "message": "Die Menge muss mindestens 1 betragen."
    }
  ]
}

Der Client kann direkt erkennen, welches Feld falsch ist und warum. Die X-Request-ID hilft dem Support, den Fehler in den Logs zu finden. Das Fehlerformat ist konsistent und maschinenlesbar.

FAQ: REST API Fehlerbehandlung

1. Was ist ein Problem Detail nach RFC 7807?

Ein Problem Detail ist ein standardisiertes Fehlerformat, das Felder wie type, title, status, detail und instance enthält. Es ermöglicht Clients, Fehler einheitlich zu verarbeiten und anzuzeigen.

2. Warum sollten APIs einheitliche Fehlerformate verwenden?

Einheitliche Fehlerformate erleichtern die Client-Implementierung und reduzieren den Aufwand für die Fehlerbehandlung. Entwickler wissen, welche Felder sie erwarten können, unabhängig vom Endpunkt.

3. Was gehört in eine Fehlerantwort?

Eine gute Fehlerantwort enthält den HTTP-Statuscode, eine Fehlerbeschreibung, eine Fehler-ID, den betroffenen Endpunkt und bei Validierungsfehlern die konkreten Felder mit den Fehlermeldungen.

4. Was ist der Unterschied zwischen 400 und 422?

400 Bad Request wird verwendet, wenn die Anfrage syntaktisch ungültig ist oder die Server die Nachricht nicht verstehen kann. 422 Unprocessable Content bedeutet, dass die Anfrage syntaktisch korrekt ist, aber semantisch nicht verarbeitet werden kann.

5. Wann verwendet man 401 und wann 403?

401 Unauthorized zeigt an, dass die Authentifizierung fehlt oder ungültig ist. 403 Forbidden zeigt an, dass der authentifizierte Benutzer nicht berechtigt ist, die Ressource zu verwenden.

6. Was ist 409 Conflict?

409 Conflict zeigt einen Konflikt an, beispielsweise bei gleichzeitigen Änderungen an derselben Ressource oder bei einer Verletzung von Geschäftsregeln. Es ist präziser als 400 Bad Request.

7. Sollte man Stacktraces in Fehlerantworten senden?

Nein, Stacktraces und interne Pfade gehören nicht in die API-Antwort. Sie können sicherheitsrelevante Informationen preisgeben und sollten nur in internen Logs gespeichert werden.

8. Was ist eine Korrelations-ID?

Eine Korrelations-ID ist ein eindeutiger Identifier, der einen Request über mehrere Systeme hinweg verfolgbar macht. Sie wird oft als X-Request-ID oder X-Correlation-ID Header übertragen und hilft bei der Fehlersuche.

9. Was ist der Vorteil von anwendungsspezifischen Fehlercodes?

Anwendungsspezifische Fehlercodes wie ORDER_NOT_FOUND oder PAYMENT_DECLINED sind präziser als allgemeine HTTP-Statuscodes. Sie ermöglichen Clients, gezielt auf bestimmte Situationen zu reagieren.

10. Was ist 429 Too Many Requests?

429 Too Many Requests zeigt an, dass der Client zu viele Anfragen in einem bestimmten Zeitraum gesendet hat. Der Server kann über Retry-After mitteilen, wann der Client die Anfrage wiederholen darf.

11. Wie behandelt man serverseitige Fehler?

Serverseitige Fehler werden mit 5xx Statuscodes gemeldet. Der Client sollte generische Fehlermeldungen erhalten, während Details intern geloggt werden. Monitoring-Systeme lösen Alerts aus.

12. Was ist der Retry-After Header?

Der Retry-After Header teilt dem Client mit, wie lange er warten soll, bevor er die Anfrage wiederholt. Er wird typischerweise bei 429 oder 503 verwendet und kann eine Sekundenanzahl oder einen Zeitpunkt enthalten.

13. Sollten Fehlermeldungen lokalisiert sein?

Ja, Fehlermeldungen können lokalisiert werden, wenn Clients über Accept-Language ihre Sprache mitteilen. Der Server antwortet dann mit entsprechenden Übersetzungen, sofern verfügbar.

14. Was ist der Unterschied zwischen title und detail?

title ist eine kurze, menschenlesbare Zusammenfassung des Fehlertyps. detail beschreibt den konkreten Fehler im Kontext der Anfrage. Beispielsweise ist title Validierungsfehler und detail Die Menge muss mindestens 1 betragen.

15. Wie testet man API-Fehlerfälle?

API-Fehlerfälle werden mit Negativtests, Contract Tests und Schema-Validierungen geprüft. Du simulierst ungültige Eingaben, fehlende Authentifizierung, Konflikte und Überlastung und verifizierst die erwarteten Statuscodes und Fehlerformate.

Weiter im API Lernpfad, Richtung Versionierung.

Der nächste Artikel im API Lernpfad behandelt API Versionierung — Strategien für REST, GraphQL und gRPC sowie Migration von API-Versionen.

Quellen

Buchempfehlungen zur API-Entwicklung

Wenn Du Dich weiter mit API Fehlerbehandlung, API Design und Softwarearchitektur beschäftigen möchtest, empfehlen wir Dir die folgenden Bücher:

API-Entwicklung

Bücher über API-Design, REST, GraphQL, OpenAPI und API-Architektur

REST und HTTP: Entwicklung und Integration nach REST-Prinzipien von Stefan Tilkov

Täglicher Artikel