Problem Details for HTTP APIs
obsoletes
- rfc-7807 — Problem Details for HTTP APIs
Extracted elements (23)
Problem details are identified by URI rather than a simple code or string because URIs allow both namespacing (to avoid collisions between different APIs) and potential dereferencing for documentation. Non-resolvable URIs (e.g., tag: scheme) are allowed but resolvable URIs are encouraged because future tooling that resolves type URIs would otherwise require a breaking change to switch.
Problem details are not intended as a debugging tool for underlying implementations; rather, they expose greater detail about the HTTP interface itself. Truly generic problems are better expressed as plain status codes, and APIs with existing error formats should use those rather than problem details.
Problem details can be used with any HTTP status code but most naturally fit 4xx and 5xx responses. The format supports content negotiation via Accept and Accept-Language headers, though negotiation may still result in a non-preferred default representation being returned.
This document obsoletes RFC 7807. Changes from RFC 7807 include: introduction of the 'HTTP Problem Types' registry (Section 4.2), clarification on how multiple problems should be treated (Section 3), and guidance for using type URIs that cannot be dereferenced (Section 3.1.1).
A problem type URI SHOULD resolve to HTML documentation that explains how to resolve the problem.
Clients consuming problem details MUST ignore any extension members that they don't recognize; this allows problem types to evolve and include additional information in the future.
Consumers MUST use the 'type' URI (after resolution, if necessary) as the problem type's primary identifier. When the 'type' member is not present, its value is assumed to be 'about:blank'.
Consumers SHOULD NOT parse the 'detail' member for information; extensions are more suitable and less error-prone ways to obtain such information.
Extension member names SHOULD start with a letter (ALPHA) and SHOULD comprise characters from ALPHA, DIGIT, and '_', and they SHOULD be three characters or longer, to allow serialization in formats other than JSON.
Generators MUST use the same status code in the actual HTTP response as is conveyed in the 'status' member, to assure that generic HTTP software that does not understand this format still behaves correctly.
If a member's value type does not match the specified type, the member MUST be ignored — processing will continue as if the member had not been present.
If a type URI is a locator (e.g., 'http' or 'https' scheme), dereferencing it SHOULD provide human-readable documentation for the problem type. However, consumers SHOULD NOT automatically dereference the type URI unless providing information to developers (e.g., in a debugging tool).
It is RECOMMENDED that absolute URIs be used in 'instance' when possible; when relative URIs are used, they should include the full path (e.g., '/instances/123') to avoid ambiguity across different resource paths.
New problem type definitions MUST document: (1) a type URI (typically with the 'http' or 'https' scheme), (2) a title that appropriately describes it, and (3) the HTTP status code for it to be used with.
When an API encounters multiple problems that do not share the same type, it is RECOMMENDED that the most relevant or urgent problem be represented in the response.
The 'about:blank' problem type is registered as the default type URI. When used, it indicates the problem has no additional semantics beyond the HTTP status code. The title SHOULD be the same as the recommended HTTP status phrase for that code (e.g., 'Not Found' for 404).
The problem details object is a JSON object serialized with the 'application/problem+json' media type. It has five defined members: 'type' (URI reference identifying the problem type), 'status' (HTTP status code), 'title' (short human-readable summary), 'detail' (occurrence-specific explanation), and 'instance' (URI reference identifying the specific occurrence).
The 'status' member is a JSON number indicating the HTTP status code generated by the origin server. It is advisory only; generators MUST use the same status code in the actual HTTP response to ensure correct behavior by generic HTTP software.
The 'title' member is a JSON string containing a short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence except for localization, and is advisory for users unaware of the type URI semantics.
This specification defines the 'HTTP Problem Types' registry for common, widely used problem type URIs. The policy is Specification Required per RFC 8126. Vendor-specific, application-specific, and deployment-specific values cannot be registered. Registrations MAY use the prefix 'https://iana.org/assignments/http-problem-types#' for the type URI.
The 'status' member duplicates the HTTP status code, creating a risk of disagreement between the two (e.g., if an intermediary changes the HTTP status code in transit). Generic HTTP software such as proxies, load balancers, firewalls, and virus scanners are unlikely to know of or respect the status code conveyed in this member.
When defining a new problem type or generating a problem response, information included must be carefully vetted to avoid leaking details that could expose attack vectors, compromise the system, or violate user privacy. Generators providing links to occurrence information should avoid exposing implementation details such as stack dumps through the HTTP interface.
The JSON format uses media type 'application/problem+json'. The XML format uses media type 'application/problem+xml' with XML namespace 'urn:ietf:rfc:7807'. In the XML format, extension arrays are serialized as elements containing child elements named 'i', and extension objects as elements containing named child elements.