4. Defining New Problem Types
When an HTTP API needs to define a response that indicates an error condition, it might be appropriate to do so by defining a new problem type.
Before doing so, it's important to understand what they are good for and what is 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 itself. Designers of new problem types need to carefully take into account the Security Considerations (Section 5), in particular, the risk of exposing attack vectors by exposing implementation internals through error messages.
Likewise, truly generic problems -- i.e., conditions that might apply to any resource on the Web -- are usually better expressed as plain status codes. For example, a "write access disallowed" problem is probably unnecessary, since a 403 Forbidden status code in response to a PUT request is self-explanatory.
Finally, an application might 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 problem details to existing HTTP APIs using HTTP content negotiation (e.g., using the Accept request header to indicate a preference for this format; see [HTTP], Section 12.5.1).
New problem type definitions MUST document:
-
a type URI (typically, with the "http" or "https" scheme)
-
a title that appropriately describes it (think short)
-
the HTTP status code for it to be used with
Problem type definitions MAY specify the use of the Retry-After response header ([HTTP], Section 10.2.3) in appropriate circumstances.
A problem type URI SHOULD resolve to HTML [HTML5] documentation that explains how to resolve the problem.
A problem type definition MAY specify additional members on the problem details object. For example, an extension might use typed links [WEB-LINKING] to another resource that machines can use to resolve the problem.
If such additional members are defined, their names SHOULD start with a letter (ALPHA, as per [ABNF], Appendix B.1) and SHOULD comprise characters from ALPHA, DIGIT ([ABNF], Appendix B.1), and "_" (so that it can be serialized in formats other than JSON), and they SHOULD be three characters or longer.
4.1. Example
For example, if you are publishing an HTTP API to your online shopping cart, you might need to indicate that the user is out of credit (our example from above) and therefore cannot make the purchase.
If you already have an application-specific format that can accommodate this information, it's probably best to do that. However, if you don't, you might use one of the problem detail formats -- JSON if your API is JSON-based or XML if it uses that format.
To do so, you might look in the registry (Section 4.2) for an already-defined type URI that suits your purposes. If one is available, you can reuse that URI.
If one isn't available, you could mint and document a new type URI (which ought to be under your control and stable over time), an appropriate title and the HTTP status code that it will be used with, along with what it means and how it should be handled.
4.2. Registered Problem Types
This specification defines the "HTTP Problem Types" registry for common, widely used problem type URIs, to promote reuse.
The policy for this registry is Specification Required, per [RFC8126], Section 4.6.
When evaluating requests, the designated expert(s) should consider community feedback, how well-defined the problem type is, and this specification's requirements. Vendor-specific, application-specific, and deployment-specific values are unable to be registered. Specification documents should be published in a stable, freely available manner (ideally located with a URL) but need not be standards.
Registrations MAY use the prefix "https://iana.org/assignments/http-problem-types#" for the type URI. Note that those URIs may not be able to be resolved.
The following template should be used for registration requests:
Type URI: [a URI for the problem type]
Title: [a short description of the problem type]
Recommended HTTP status code: [what status code is most appropriate to use with the type]
Reference: [to a specification defining the type]
See the registry at https://iana.org/assignments/http-problem-types for details on where to send registration requests.
4.2.1. about:blank
This specification registers one Problem Type, "about:blank", as follows.
Type URI: about:blank
Title: See HTTP Status Code
Recommended HTTP status code: N/A
Reference: RFC 9457
The "about:blank" URI [ABOUT], when used as a problem type, indicates that the problem has no additional semantics beyond that of the HTTP status code.
When "about:blank" is used, the title SHOULD be the same as the recommended HTTP status phrase for that code (e.g., "Not Found" for 404, and so on), although it MAY be localized to suit client preferences (expressed with the Accept-Language request header).
Please note that according to how the "type" member is defined (Section 3.1), the "about:blank" URI is the default value for that member. Consequently, any problem details object not carrying an explicit "type" member implicitly uses this URI.