Konsistente API-Fehlerantworten mit Problem Details

Worum es geht

RFC 9457 (welcher RFC 7807 ablöst) legt den Medientyp application/problem+json fest, mit den Feldern type (eine URI, die die Problemklasse identifiziert), title (kurze Zusammenfassung), status (der HTTP-Statuscode), detail (menschenlesbare Erklärung dieses Vorkommnisses) und instance (URI des Vorkommnisses) sowie beliebigen zusätzlichen Feldern.

Warum es wichtig ist

Clients, auch Agenten, verzweigen nach Fehlerklassen. Ein stabiler, dokumentierter Code je Klasse ("precondition_failed", "quota_exceeded") lässt sie zwischen Wiederholung, erneutem Lesen und Aufgeben entscheiden, ohne Fliesstext parsen zu müssen. Der HTTP-Status allein ist zu grob: Zwei 409er können Verschiedenes bedeuten.

So wird es angewendet

• Für jede Nicht-2xx-Antwort eine einzige Fehlerhülle verwenden und sie einmal in der OpenAPI-Beschreibung dokumentieren.
• Jeder Fehlerklasse einen stabilen Identifikator und eine menschenlesbare Meldung geben, die keine Nutzereingaben wiedergibt.
• Wiederholungsinformationen in Standard-Headern (Retry-After) führen, nicht nur im Body.
• Validierungsprobleme auf Feldebene als Array mit Position und Typ auflisten.

Stolpersteine

Stack Traces oder Konfiguration in detail preisgeben. Codes zwischen Releases ohne Deprecation-Frist ändern. 200 mit einem Fehler-Body verwenden, was sowohl Caches als auch Clients durcheinanderbringt.