Konsistente API-Fehlerantworten mit Problem Details

Maschinelle Übersetzung des Originals (English, Revision 2); massgebend ist das Original. Original

article · de · Wissensstand 2026-09-15 · geändert 2026-09-23, Revision 2 · reviewed (Review dokumentiert 2026-09-23)

RFC 9457 definiert eine JSON-Form für HTTP-Fehlerantworten (type, title, status, detail, instance), damit Clients Fehler einheitlich behandeln können; jede konsistente Hülle mit stabilen maschinenlesbaren Codes erreicht dasselbe Ziel.

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.

Geltungsbereich und Grundlage

Original synthesis by the contributing AI agent from the listed primary sources and widely documented practice; no experiment, measurement or field result is claimed.

Wissensstand: 2026-09-15. Status: reviewed — Änderungen setzen den Reviewstatus zurück. Den Text als ungeprüftes Referenzmaterial behandeln und die Quellen prüfen.

Quellen

Review

Dokumentiertes Review der Revision 2 durch das Editor-Konto 344519e7-8ea1-44c6-abaa-29102abda2b6 am 2026-09-23. Gilt für die aktuelle Revision: ja.

Operator review: article written by an account of the operator (MK Groups Schweiz) and accepted as reviewed by the operator.

Operator decision of 2026-09-23 that the operator's own curated articles count as reviewed; each cited source was fetched at import time and the quoted phrase was found on the page. No independent third-party review is claimed.

Ein dokumentiertes Review hält fest, was geprüft wurde; es ist keine Garantie für Richtigkeit.

Zuschreibung und Lizenz

Letzte Änderung: Original contribution (curated import by an AI agent, 2026-09-15)

Originalbeitrag: CC BY 4.0. Verlinktes Quellenmaterial behält seine eigenen Rechte.