API-Fehlermeldungen nach RFC 9457 (Problem Details)

Worum es geht

RFC 9457 löst RFC 7807 ab und beschreibt ein JSON-Objekt, das ein Server mit dem Medientyp application/problem+json (oder application/problem+xml) als Antwortkörper bei Fehlern sendet. Die Felder: type – eine URI, die die Fehlerklasse identifiziert und beim Aufruf idealerweise eine Beschreibung liefert; fehlt sie, gilt about:blank. title – eine kurze, für alle Vorkommen dieser Klasse gleiche Zusammenfassung. status – der HTTP-Statuscode als Zahl. detail – eine Erklärung dieses konkreten Vorkommens. instance – eine URI, die dieses Vorkommen bezeichnet. Eigene Erweiterungsfelder («Extension Members») sind ausdrücklich vorgesehen, etwa eine Liste von Feldfehlern bei der Validierung.

Warum es wichtig ist

Der Statuscode allein ist zu grob: Zwei 409-Antworten können «Version veraltet» und «Name schon vergeben» bedeuten und verlangen verschiedene Reaktionen. Ein Client, der auf type verzweigen kann, entscheidet zwischen Wiederholen, Neuladen und Aufgeben, ohne einen Meldungstext zu parsen, der sich mit der nächsten Version ändert. Für Agenten, die APIs aus der Dokumentation heraus benutzen, ist ein stabiler, dokumentierter Fehlerkatalog die Voraussetzung, um nicht zu raten.

So wird es angewendet

• Ein Fehlerformat für alle Nicht-2xx-Antworten, einmal in der OpenAPI-Beschreibung definiert und von jedem Endpunkt referenziert.
• Pro Fehlerklasse eine stabile type-URI unter der eigenen Domain (etwa https://api.example.ch/probleme/kontingent-erschoepft), die auf eine Seite mit Bedeutung, typischem Status und empfohlener Reaktion zeigt; die Liste gehört in die API-Dokumentation.
• type und title bleiben über Versionen stabil; nur detail beschreibt den Einzelfall und gibt Eingaben der Nutzerin nicht unverändert zurück.
• Wiederholungshinweise in Standard-Headern (Retry-After) transportieren; das Problemobjekt darf sie zusätzlich nennen.
• Validierungsfehler als Erweiterungsfeld mit einer Liste aus Feldpfad, Fehlerart und Meldung, damit ein Client alle Mängel auf einmal anzeigen kann.
• status im Körper muss dem tatsächlich gesendeten HTTP-Status entsprechen; die RFC bezeichnet das Feld als beratend, damit ein Client den ursprünglichen Status auch dann kennt, wenn eine Zwischenstation ihn verändert hat.

Stolpersteine

Stack-Traces, interne Hostnamen oder SQL in detail. Status 200 mit einem Fehlerobjekt im Körper, was Caches und Clients gleichermassen täuscht. Fehlerklassen umbenennen ohne Übergangsfrist. Eine type-URI, die auf eine 404-Seite zeigt. Das Format nur bei manchen Endpunkten einführen, sodass Clients zwei Parser brauchen.