1. Introduction (Einführung)

HTTP-Statuscodes (Abschnitt 15 von [HTTP]) können nicht immer genügend Informationen über Fehler übermitteln, um hilfreich zu sein. Während Menschen, die Webbrowser verwenden, häufig HTML [HTML5]-Antwortinhalte verstehen können, haben nicht-menschliche Konsumenten von HTTP-APIs Schwierigkeiten damit.

Um diesem Mangel zu begegnen, definiert diese Spezifikation einfache JSON [JSON]- und XML [XML]-Dokumentformate, um die Details eines aufgetretenen Problems zu beschreiben -- "Problemdetails" (problem details).

Betrachten Sie zum Beispiel eine Antwort, die anzeigt, dass das Konto des Clients nicht über ausreichendes Guthaben verfügt. Der Designer der API könnte sich entscheiden, den Statuscode 403 Forbidden zu verwenden, um generische HTTP-Software (wie Client-Bibliotheken, Caches und Proxies) über die allgemeine Semantik der Antwort zu informieren. API-spezifische Problemdetails (wie der Grund, warum der Server die Anfrage abgelehnt hat, und der anwendbare Kontostand) können im Antwortinhalt übertragen werden, sodass der Client entsprechend handeln kann (zum Beispiel eine Überweisung von mehr Guthaben auf das Konto auslösen).

Diese Spezifikation identifiziert den spezifischen "Problemtyp" (problem type) (z.B. "out of credit") mit einem URI [URI]. HTTP-APIs können URIs unter ihrer Kontrolle verwenden, um für sie spezifische Probleme zu identifizieren, oder sie können bestehende URIs wiederverwenden, um Interoperabilität zu erleichtern und gemeinsame Semantik zu nutzen (siehe Abschnitt 4.2).

Problemdetails können weitere Informationen enthalten, wie z.B. einen URI, der das spezifische Auftreten des Problems identifiziert (was effektiv dem Konzept "Die Zeit, als Joe letzten Donnerstag nicht genug Guthaben hatte" eine Kennung gibt), was für Support- oder Forensikzwecke nützlich sein kann.

Das Datenmodell für Problemdetails ist ein JSON [JSON]-Objekt; wenn es als JSON-Dokument serialisiert wird, verwendet es den Medientyp "application/problem+json". Anhang B definiert ein äquivalentes XML-Format, das den Medientyp "application/problem+xml" verwendet.

Wenn sie in einer HTTP-Antwort übermittelt werden, kann der Inhalt von Problemdetails unter Verwendung proaktiver Verhandlung ausgehandelt werden; siehe Abschnitt 12.1 von [HTTP]. Insbesondere kann die Sprache, die für menschenlesbare Zeichenketten verwendet wird (wie die in title und description), unter Verwendung des Accept-Language-Request-Header-Feldes (Abschnitt 12.5.4 von [HTTP]) ausgehandelt werden, obwohl diese Verhandlung dennoch dazu führen kann, dass eine nicht bevorzugte Standarddarstellung zurückgegeben wird.

Problemdetails können mit jedem HTTP-Statuscode verwendet werden, passen aber am natürlichsten zur Semantik von 4xx- und 5xx-Antworten. Beachten Sie, dass Problemdetails (natürlich) nicht die einzige Möglichkeit sind, Details eines Problems in HTTP zu übermitteln. Wenn die Antwort immer noch eine Darstellung einer Ressource ist, ist es beispielsweise oft vorzuziehen, die relevanten Details im Format dieser Anwendung zu beschreiben. Ebenso decken definierte HTTP-Statuscodes viele Situationen ab, ohne dass zusätzliche Details übermittelt werden müssen.

Das Ziel dieser Spezifikation ist es, gemeinsame Fehlerformate für Anwendungen zu definieren, die eines benötigen, damit sie nicht gezwungen sind, ihr eigenes zu definieren oder, schlimmer noch, versucht sind, die Semantik bestehender HTTP-Statuscodes neu zu definieren. Selbst wenn eine Anwendung sich entscheidet, es nicht zur Übermittlung von Fehlern zu verwenden, kann die Überprüfung ihres Designs helfen, die Designentscheidungen zu leiten, die bei der Übermittlung von Fehlern in einem bestehenden Format getroffen werden.

Siehe Anhang D für eine Liste der Änderungen gegenüber [RFC7807].