Konsistente REST API Errors: Struktur, Statuscodes und Beispiele

Gute APIs liefern nicht nur Daten. Sie liefern vor allem klare Fehler. Wenn etwas schiefgeht, willst du sofort wissen was, warum und was als Nächstes zu tun ist. Ein konsistentes Fehlerdesign spart dir Debug-Zeit, reduziert Supportaufwand und macht Clients robuster.

In diesem Guide lernst du, wie du HTTP-Statuscodes, ein einheitliches JSON-Schema, feingranulare Fehlertypen und nützliche Metadaten kombinierst. Ziel ist, dass du vom ersten Projekt an nachvollziehbare, maschinenlesbare und menschenfreundliche Fehler erzeugst – inklusive verständlicher Beispiele.

Warum konsistente Fehler das Fundament sind

Inkonsistente Fehler kosten Zeit. Unterschiedliche Formen, fehlende Felder oder wechselnde Sprachen führen zu fragilen Clients und Missverständnissen. Mit einer stabilen Struktur erreichst du, dass jede Fehlermeldung vorhersehbar ist: Der Client weiß immer, wo message, code und details stehen und wie er reagieren kann.

Grundprinzipien für gutes Fehlerdesign

Klare HTTP-Statuscodes

Nutze 4xx für Clientfehler und 5xx für Serverfehler. Halte dich an wenige, gut erklärte Codes: 400 (ungültige Anfrage), 401 (nicht authentifiziert), 403 (keine Berechtigung), 404 (nicht gefunden), 409 (Konflikt), 422 (Validierung), 429 (Rate Limit), 500 (Serverfehler), 503 (Wartung).

Einheitliches JSON-Schema

Definiere eine gleichbleibende Form. So können Frontends und Integrationen Fehler automatisiert auswerten.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Ressource wurde nicht gefunden",
    "details": [],
    "traceId": "b7a1c4f2d9",
    "status": 404
  }
}

Wichtig: code ist maschinenlesbar, message ist menschlich, traceId hilft beim Debugging, status spiegelt den HTTP-Code.

Keine Interna leaken

Stacktraces, SQL, Pfade oder Konfigurationen gehören nicht in die Response. Logge intern vollständig, liefere extern sparsam und zielgerichtet.

Eindeutige Fehlercodes

Halte eine Liste kanonischer Fehlercodes bereit, z. B. VALIDATION_FAILED, UNAUTHORIZED, FORBIDDEN, RESOURCE_NOT_FOUND, CONFLICT, RATE_LIMITED. So bleibt dein Verhalten vorhersehbar.

Referenzen und Korrelation

Gib eine traceId oder correlationId zurück und logge sie serverseitig. Der Support kann damit Fehler schnell nachverfolgen.

JSON-Varianten, die sich bewährt haben

RFC 7807 Problem Details

Du kannst das Standardformat nutzen. Es ist weit verbreitet und lässt sich erweitern.

Header: Content-Type: application/problem+json
Body:

{
  "type": "https://api.example.com/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "Einige Felder sind ungültig",
  "instance": "/orders/123",
  "errors": [
    {"path": "email", "message": "Ungültige Adresse"},
    {"path": "quantity", "message": "Muss >= 1 sein"}
  ],
  "traceId": "b7a1c4f2d9"
}

Vorteil: Standardfelder wie type, title, status. Eigene Felder (z. B. errors, traceId) sind erlaubt.

Eigenes, schlankes Schema

Wenn du RFC 7807 nicht nutzen willst, bleibe stringent bei deinem Schema. Entscheidend ist Konstanz über alle Endpunkte.

Gute Fehlermeldungen schreiben

Menschen lesen die message

Halte die message kurz, klar und handlungsorientiert: was ist falsch und wie es richtig geht. Vermeide Jargon. Beispiel: „Token fehlt oder ist abgelaufen. Bitte neu anmelden.“

Maschinen lesen den code

Der code bleibt stabil, auch wenn sich die message ändert. Der Client schaltet seine Logik auf den code, nicht auf freie Texte.

Details präzisieren

Bei Validierung sind feldgenaue Details Gold wert. Nutze path oder field und beschreibe den Verstoß verständlich.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Eingaben prüfen",
    "status": 422,
    "details": [
      {"path": "email", "rule": "format", "message": "Ungültige E-Mail"},
      {"path": "items[0].quantity", "rule": "min", "expected": 1, "actual": 0}
    ],
    "traceId": "b7a1c4f2d9"
  }
}

Typische Fehlerfälle mit Beispielen

400 Bad Request – ungültige Anfrage

Die Struktur passt nicht oder Felder fehlen.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":{"code":"BAD_REQUEST","message":"JSON unlesbar","status":400,"traceId":"b7a1c4f2d9"}}

401 Unauthorized – Authentifizierung fehlt

{"error":{"code":"UNAUTHORIZED","message":"Token fehlt oder ist ungültig","status":401,"traceId":"b7a1c4f2d9"}}

403 Forbidden – Berechtigung fehlt

{"error":{"code":"FORBIDDEN","message":"Rolle reicht nicht aus","status":403,"traceId":"b7a1c4f2d9"}}

404 Not Found – Ressource nicht vorhanden

{"error":{"code":"RESOURCE_NOT_FOUND","message":"Kunde 7129 existiert nicht","status":404,"traceId":"b7a1c4f2d9"}}

409 Conflict – Zustand verhindert Aktion

{"error":{"code":"CONFLICT","message":"Bestellung ist bereits bezahlt","status":409,"traceId":"b7a1c4f2d9"}}

422 Unprocessable Entity – Validierung

{"error":{"code":"VALIDATION_FAILED","message":"Eingaben prüfen","status":422,"details":[{"path":"email","message":"Ungültige Adresse"}],"traceId":"b7a1c4f2d9"}}

429 Too Many Requests – Rate Limit

Setze Retry-After im Header und nenne das Limit.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100

{"error":{"code":"RATE_LIMITED","message":"Zu viele Anfragen. Später erneut versuchen","status":429,"traceId":"b7a1c4f2d9"}}

500/503 Serverfehler – intern oder Wartung

{"error":{"code":"INTERNAL_ERROR","message":"Unerwarteter Fehler. Bitte später erneut versuchen","status":500,"traceId":"b7a1c4f2d9"}}

Versionierung, Sprache und Stabilität

Halte das Fehlerschema stabil. Wenn du Felder änderst, erhöhe API-Version und dokumentiere die Migration. Internationalisierung: code bleibt gleich, message darf lokalisiert sein. Verwende Accept-Language oder einen eigenen Header, um die Sprache sauber zu wählen.

Sicherheit und Datenschutz

Zeige keine sensiblen Daten in Fehlermeldungen. Bei 401 gib keine Details, ob der Benutzer existiert. Bei 404 verrate nicht, ob eine vertrauliche ID gültig ist, wenn das Information leakt. Logge intern vollständig mit traceId, aber minimiere externe Informationen.

Wie Clients gut mit Fehlern umgehen

Clients sollten status und code prüfen, messages nur anzeigen, nicht parsen. Implementiere Backoff bei 429/503, respektiere Retry-After, unterscheide dauerhafte von temporären Fehlern und zeige dem Nutzer klare nächste Schritte.

Mini-Checkliste für deinen ersten Entwurf

Definiere Statuscodes pro Fehlerklasse. Lege Error-Codes fest. Schreibe ein JSON-Schema mit message, code, status, traceId, optional details. Baue Beispiele in die Doku ein. Teste mit absichtlichen Fehlern in deiner Staging-Umgebung. Dokumentiere Rate Limits und Wartungsfenster.

Fazit

Konsistente Fehler sind Teil deiner API-Features. Mit klaren Statuscodes, stabilem JSON-Schema, präzisen Codes, verständlichen Messages und traceId werden Probleme sichtbar und lösbar. Baue diese Struktur früh in dein Projekt ein und halte sie konsequent ein. So wächst deine API zuverlässig – und Entwickler lieben es, damit zu arbeiten.