Indicating Details of Problems to Machines in HTTP

While HTTP defines the status code as the primary indicator of generic response semantics, it is sometimes not fine-grained enough to convey helpful information about the error, particularly to non-human consumers. For example, consider a 403 Forbidden response that indicates that the client's account doesn't have enough credit. While this can be adequately expressed in HTML if it's presented to a human in front of a Web browser, a non-browser client will have difficulty understanding the response, because it doesn't understand the structure of the markup. This specification defines a "Problem Detail" as an extensible way to carry machine-readable details of errors in a response, to avoid the need to invent new, application-specific response formats. The common data model for problem details as a JSON object. That object can be serialised as an "application/json-problem" HTTP response, or it can be conveyed using a Link HTTP response header field . Note that this format is (naturally) not the only way to convey the details of a problem in HTTP; if the response is still a representation of a resource, for example, it's often preferable to accommodate describing the details in that format. As such, the aim of this specification is to define a common format for those applications that need one, so that they aren't required to define their own.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

The canonical format for problem details is a JSON document, identified with the "application/json-problem" media type. Its root object has the following properties: "describedby" (string) - An absolute URI that identifies the type of problem. When dereferenced, it SHOULD provide human-readable documentation (e.g., using HTML). "title" (string) - A short, human-readable summary of the problem. It SHOULD NOT change from instance to instance of the problem, except for purposes of localisation. "instance" (string) - An absolute URI that identifies the specific instance of the problem. It may or may not yield further information if dereferenced. "detail" (string) - Optionally, an additional, human readable explanation specific to this instance of the problem. Problem details, when serialised as JSON objects, MUST include the "describedby" and "title" properties. The "instance" and "detail" properties are always OPTIONAL. Problem types MAY extend their instances with additional properties. For example:

Here, the out-of-credit problem (identified by its URI) indicates the reason for the 403 in "title", gives a reference for the specific problem occurrence with "instance" and gives instance-specific details in "detail", and adds two extensions; "balance" conveys the account's balance, and "account" gives a link where the account can be topped up. Note that "describedby" is case-sensitive in the JSON object, as are all other property names.

Because resources often use formats other than JSON to convey human-readable problem details, it is also possible to serialise Problem Details for non-browser consumption alongside them using a Link response header field . For example:

; rel="describedby"; instance="http://server.example.net/problems/12345abc"; title="You do not have enough credits."; balance=30; account="http://api.example.com/account/12345" ]]> Here, the same problem as above is conveyed using the header in previous examples, but without the optional detail. Problem details are serialised into Link headers using the "describedby" link relation type, with the URL for the problem type as the link target. The title is conveyed using the "title" parameter, and the detail can be conveyed using the "detail" parameter. Extension parameters on the JSON Object can also be expressed as target parameters on the link header, as long as the extension either defines them as a string, or explains how to express them as one. The title, detail, and extension properties MUST use the encoding specified in if it falls outside of the US-ASCII character set. For example, the following are all valid:

; rel="describedby"; title="Hi" Link: ; rel="describedby"; title="Hi" Link: ; rel="describedby"; title="Hi there"; detail="something happened." Link: ; rel="describedby"; other="foo"; title="Hi there"; title*=UTF-8''Hi%20there; another=bar; detail*=UTF-8''something%20happened ]]>

Before defining a new type of problem detail, it’s important to understand what they are good for, and what’s better left to other mechanisms. Problem details are not a debugging tool for the underlying implementation; rather, they are a way to expose greater detail about the HTTP interface of the application itself. For example, an "out of credit" problem is an appropriate explanation as to why a request was forbidden. In contrast, a description of the internal conditions that led to a 500 Internal Server Error along with a stack trace are not an appropriate use of this mechanism, because it exposes implementation detail, rather than explaining the interface. At the other end of the spectrum, truly generic problems – i.e., conditions that could potentially apply to any resource on the Web – are usually better expressed as plain status codes. For example, a "write access disallowed" problem is unnecessary, since a 403 Forbidden status code on a PUT request is self-explanatory. Finally, a problem domain may have a more appropriate way to carry an error in a format that it already defines. Problem details are intended to avoid the necessity of establishing new "fault" or "error" document formats, not to replace existing domain-specific formats. That said, it is possible to add support for problems using HTTP server-driven content negotiation (i.e., the client uses the Accept request header to indicate a preference for problems). If defining a new problem still seems wise, one can be created by: Nominating a describedby URL (typically, with the "http" scheme), Choosing a title that appropriately describes it (think short), and Nominating a HTTP status code for it to be used with. Problem types MAY specify the use of the Retry-After response header in appropriate circumstances. A problem’s describedby URL SHOULD resolve to HTML documentation that explains how to resolve the problem. Optionally, a problem definition MAY specify additional properties on the Problem Details JSON object. For example, an extension might use typed links to another resource that can be used by machines to resolve the problem. If an extension is defined, its name SHOULD conform to token , so that it can be serialised in header and other formats. Likewise, problems defining extensions should either make their values strings, or explain how to map their values to strings that are safe to include in HTTP headers (noting the special semantics of a comma there).

The URL used in the describedby property MUST NOT be changed in any way from that defined by its specification; doing so turns it into a different problem that most consumers will not recognise. The title string SHOULD be sent as specified by the problem definition, although it MAY be localised (e.g., using server-driven content negotiation, with the "Accept-Language" request header). Remember that such responses are required by HTTP to include a Vary header, e.g.:

; rel="describedby"; title*=UTF-8''Du%20%C3%A4r%20ute%20p%C3%A5%20pengar. ]]> Note the use of RFC5987 encoding here. Problem details SHOULD be served with Content-Language headers, even if negotiation isn't used, to aid in localisation. The information conveyed in the detail property, if present, SHOULD focus on helping the client correct the problem, rather than giving debugging information. The instance property, if present, MUST be globally unique to that particular occurrence of the problem. Software that generates problems should note that only one problem can be sent at at time.

Consumers should use the describedby URL as the primary identifier for the problem; the title string is advisory, and included only for users who are not aware of the semantics of the URL, and don’t have the ability to discover them (e.g., offline log analysis). Likewise, the detail property SHOULD NOT be parsed for information by clients; extensions are more suitable and less error-prone ways to obtain such information. Clients consuming problem details MUST ignore unrecognised extensions; this allows problems to evolve and include additional information in the future. Finally, clients consuming problem details SHOULD NOT automatically deference the describedby URL; it is not intended for machine interaction.

When defining a new problem, the information included must be carefully vetted. Likewise, when actually generating a problem – however it is serialised – the details given must also be scrutinised. Risks include leaking information that can be exploited to compromise the system, access to the system, or the privacy of users of the system.

This specification defines a new Internet media type, "application/json-problem":

Intended usage: COMMON Restrictions on usage: None. Author: Mark Nottingham Change controller: IESG ]]>

The author would like to thank Jan Algermissen, Mike Amundsen, Subbu Allamaraju, Roy Fielding, Sam Johnston, Julian Reschke, James Snell, and Erik Wilde for early review of this specification (even if some disagree with parts of it).