Problem Details for HTTP APIs

Problem details are intentionally not a debugging tool for server implementation internals; they expose greater detail about the HTTP interface itself. This distinction guides what information is appropriate to include and avoids exposing attack vectors through error messages.

http, json

The aim of this specification is to define a common error format so that HTTP APIs do not each define their own 'fault' or 'error' document format, and are not tempted to redefine the semantics of existing HTTP status codes.

http, json

The specification uses a URI as the primary problem type identifier (rather than a code or enum) so that HTTP APIs can nominate new URIs under their control or reuse existing ones, enabling a decentralized, extensible type system without a central registry.

http, json

Both 'type' and 'instance' accept relative URIs, which must be resolved relative to the document's base URI per RFC 3986 Section 5. Implementers must handle this resolution correctly.

http, json

Problem details can be added to existing HTTP APIs via content negotiation (e.g., using the Accept request header to indicate preference for 'application/problem+json'), without breaking clients that do not support the format.

http, json

Problem details can be embedded in formats other than JSON and XML (e.g., HTML) either by encapsulating a JSON or XML serialization or by translating the problem detail model into the target format's conventions. No specific recommendation is made; the appropriate method depends on format and application.

http, json

When multiple subproblems of different HTTP status codes must be conveyed in one response, the 207 (Multi-Status) code can be used to encapsulate multiple status messages, since all subproblems in a single problem details object share the same HTTP status code.

http, json

A problem type's URI SHOULD resolve to HTML documentation explaining how to resolve the problem.

http, json

Clients consuming problem details MUST ignore any extension members they do not recognize, allowing problem types to evolve and add information without breaking existing clients.

http, json

Consumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory only, for users who cannot discover the URI semantics.

http, json

Consumers SHOULD NOT automatically dereference the type URI.

http, json

Extension member names SHOULD start with a letter (ALPHA) and SHOULD consist of characters from ALPHA, DIGIT, and '_', and SHOULD be three characters or longer, so they can be serialized in formats other than JSON.

http, json

Generators MUST use the same HTTP status code in the actual HTTP response as conveyed in the 'status' member, to ensure generic HTTP software behaves correctly even without understanding the problem details format.

http, json

New problem type definitions MUST document: (1) a type URI (typically 'http' or 'https' scheme), (2) a short title, and (3) the HTTP status code for use with the problem type.

http, json

A problem details object is a JSON object identified by the 'application/problem+json' media type. It carries machine-readable error details for HTTP APIs, identifying the problem type with a URI and optionally conveying status code, title, detail, and instance URI.

http, json

Problem type definitions MAY extend the problem details object with additional members, effectively namespaced by the problem type URI. New 'standard' members cannot be defined without defining a new media type.

http, json

The 'about:blank' URI, when used as the 'type' value, indicates the problem has no additional semantics beyond the HTTP status code. It is the default value for 'type' when that member is absent. The 'title' SHOULD be the standard HTTP status phrase for the code.

http, json

The 'detail' member is a human-readable explanation specific to this occurrence of the problem. It SHOULD focus on helping the client correct the problem rather than providing debugging information; consumers SHOULD NOT parse it for machine-extractable information.

http, json

The 'instance' member is a URI reference identifying the specific occurrence of the problem. It may or may not yield further information if dereferenced, and effectively gives an identifier to a single problem occurrence.

http, json

The 'status' member conveys the HTTP status code for consumer convenience. Generators MUST use the same status code in the actual HTTP response. The member is advisory; generic HTTP software uses the HTTP status code, not this field.

http, json

The 'title' member is a short, human-readable summary of the problem type that SHOULD NOT change between occurrences except for localization. It is advisory only; consumers MUST use 'type' as the primary identifier.

http, json

The 'type' member is a URI reference identifying the problem type; when absent its value defaults to 'about:blank'. When dereferenced it SHOULD provide human-readable HTML documentation for the problem type.

http, json

This document registers the 'application/problem+json' media type with IANA. Required parameters: none. Encoding considerations same as RFC 7159 (JSON). Intended usage: COMMON.

http, json, registry

This document registers the 'application/problem+xml' media type with IANA. Required parameters: none. Encoding considerations same as RFC 7303 (XML). Intended usage: COMMON.

http, json, registry

Information included in a problem details response must be carefully vetted to avoid leaking exploitable implementation details such as stack traces, internal data structures, or access control information that could compromise system security or user privacy.

http, security

The 'status' member can disagree with the actual HTTP status code (e.g., if an intermediary modifies the code in transit). Generic software such as proxies, load balancers, and firewalls will not respect the status code in the problem body; both generators and consumers must be aware of this ambiguity.

http, security

The JSON serialization uses the 'application/problem+json' media type. Fields are: 'type' (string, URI reference), 'title' (string), 'status' (number), 'detail' (string), 'instance' (string, URI reference), plus optional extension members.

http, json

The XML serialization uses the 'application/problem+xml' media type and the namespace 'urn:ietf:rfc:7807'. Extension arrays are expressed as elements with 'i' children; extension objects are elements with child elements. All extensions MUST use the RFC 7807 namespace only.

http, json