One document matched: draft-nottingham-http-problem-01.xml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE rfc SYSTEM "http://xml.resource.org/authoring/rfc2629.dtd" [
<!ENTITY rfc2119 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc2616 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml'>
<!ENTITY rfc3986 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
<!ENTITY rfc4627 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml'>
<!ENTITY rfc5987 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5987.xml'>
<!ENTITY rfc5988 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml'>
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc tocdepth="3" ?>
<?rfc tocindent="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes" ?>
<rfc ipr="trust200902" docName="draft-nottingham-http-problem-01" category="info">
<front>
<title abbrev="Problem Details">Indicating Details of Problems to Machines in HTTP</title>
<author initials="M." surname="Nottingham" fullname="Mark Nottingham">
<organization></organization>
<address>
<email>mnot@mnot.net</email>
<uri>http://www.mnot.net/</uri>
</address>
</author>
<date year="2012"/>
<keyword>status</keyword>
<keyword>HTTP</keyword>
<keyword>error</keyword>
<keyword>problem</keyword>
<abstract>
<t>This document defines a "Problem Detail" as an extensible
way to carry machine-readable details of HTTP errors in a response,
to avoid the need to invent new response formats for non-human
consumers.</t>
</abstract>
<note title="Note to Readers">
<t>This draft should be discussed on the <eref
target="https://www.ietf.org/mailman/listinfo/apps-discuss">apps-discuss
mailing list</eref>.</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>While HTTP <xref target="RFC2616"/> 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.</t>
<t>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.</t>
<t>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.</t>
<t>The common data model for problem details as a JSON <xref
target="RFC4627"/> 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 <xref target="RFC5988"/>.</t>
<t>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.</t>
<t>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.</t>
</section>
<section title="Requirements">
<t>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 <xref
target="RFC2119"/>.</t>
</section>
<section title="The Problem Details JSON Object">
<t>The canonical format for problem details is a JSON <xref
target="RFC4627"/> document, identified with the
"application/json-problem" media type. Its root object has the
following properties:</t>
<t><list style='symbols'>
<t>"describedby" (string) - An absolute URI <xref
target="RFC3986"/> that identifies the type of problem. When
dereferenced, it SHOULD provide human-readable documentation
(e.g., using HTML).</t>
<t>"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.</t>
<t>"instance" (string) - An absolute URI that identifies the
specific instance of the problem. It may or may not yield further
information if dereferenced.</t>
<t>"detail" (string) - Optionally, an additional, human readable
explanation specific to this instance of the problem.</t>
</list></t>
<t>Problem details, when serialised as JSON objects, MUST include
the "describedby" and "title" properties. The "instance" and
"detail" properties are always OPTIONAL.</t>
<t>Problem types MAY extend their instances with additional
properties. For example:</t>
<figure><artwork><![CDATA[
HTTP/1.1 403 Forbidden
Content-Type: application/json-problem
Content-Language: en
{
"describedby": "http://example.com/probs/out-of-credit",
"title": "You do not have enough credits.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "http://server.example.net/problems/12345abc",
"balance": 30,
"account": "http://api.example.com/account/12345"
}]]></artwork></figure>
<t>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.</t>
<t>Note that "describedby" is case-sensitive in the JSON object, as
are all other property names.</t>
</section>
<section anchor="the-problem-http-response-header-field" title="Expressing Problem Details with Link Headers">
<t>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 <xref target="RFC5988"/>. For example:</t>
<figure><artwork><![CDATA[
HTTP/1.1 403 Forbidden
Content-Type: text/html
Content-Language: en
Link: <http://example.com/probs/out-of-credit>; 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"
]]></artwork></figure>
<t>Here, the same problem as above is conveyed using the header in
previous examples, but without the optional detail.</t>
<t>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.</t>
<t>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.</t>
<t>The title, detail, and extension properties MUST use the encoding
specified in <xref target="RFC5987"/> if it falls outside of the
US-ASCII character set.</t>
<t>For example, the following are all valid:</t>
<figure><artwork><![CDATA[
Link: <http://example.com/p/1>; rel="describedby"; title="Hi"
Link: <ftp://example.com/p/1>; rel="describedby"; title="Hi"
Link: <http://example.com/p/1>; rel="describedby";
title="Hi there"; detail="something happened."
Link: <http://example.com/p/1>; rel="describedby"; other="foo";
title="Hi there"; title*=UTF-8''Hi%20there; another=bar;
detail*=UTF-8''something%20happened
]]></artwork></figure>
</section>
<section anchor="defining" title="Defining New Problem Details">
<t>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.</t>
<t>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.</t>
<t>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.</t>
<t>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.</t>
<t>For example, a "write access disallowed" problem is
unnecessary, since a 403 Forbidden status code on a PUT request is
self-explanatory.</t>
<t>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).</t>
<t>If defining a new problem still seems wise, one can be created
by:
<list style="numbers">
<t>Nominating a describedby URL (typically, with the "http"
scheme),</t>
<t>Choosing a title that appropriately describes it (think
short), and</t>
<t>Nominating a HTTP status code for it to be used with.</t>
</list></t>
<t>Problem types MAY specify the use of the Retry-After response
header in appropriate circumstances.</t>
<t>A problem’s describedby URL SHOULD resolve to HTML documentation
that explains how to resolve the problem.</t>
<t>Optionally, a problem definition MAY specify additional properties
on the Problem Details JSON object.</t>
<t>For example, an extension might use typed links <xref
target="RFC5988"/> to another resource that can be used by machines
to resolve the problem.</t>
<t>If an extension is defined, its name SHOULD conform to token <xref
target="RFC2616"/>, so that it can be serialised in header and other
formats.</t>
<t>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).</t>
</section>
<section anchor="generating-problems" title="Generating
Problem Details">
<t>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.</t>
<t>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.:</t>
<figure><artwork><![CDATA[
HTTP/1.1 403 Forbidden
Content-Type: text/html
Content-Language: se
Vary: Accept-Language
Link: <http://example.com/probs/out-of-credit>;
rel="describedby";
title*=UTF-8''Du%20%C3%A4r%20ute%20p%C3%A5%20pengar.
]]></artwork></figure>
<t>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.</t>
<t>The information conveyed in the detail property, if present,
SHOULD focus on helping the client correct the problem, rather than
giving debugging information.</t>
<t>The instance property, if present, MUST be globally unique to
that particular occurrence of the problem.</t>
<t>Software that generates problems should note that only one
problem can be sent at at time. </t>
</section>
<section anchor="consuming-problems" title="Consuming Problem Details">
<t>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).</t>
<t>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.</t>
<t>Clients consuming problem details MUST ignore unrecognised
extensions; this allows problems to evolve and include additional
information in the future. </t>
<t>Finally, clients consuming problem details SHOULD NOT
automatically deference the describedby URL; it is not intended for
machine interaction.</t>
</section>
<section title="Security Considerations">
<t>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.</t>
<t>Risks include leaking information that can be exploited to
compromise the system, access to the system, or the privacy of
users of the system.</t>
</section>
<section title="IANA Considerations">
<t>This specification defines a new Internet media type,
"application/json-problem":</t>
<figure><artwork><![CDATA[
Type name: application
Subtype name: json-problem
Required parameters: None
Optional parameters: None; unrecognised parameters
should be ignored
Encoding considerations: Same as [RFC4627]
Security considerations: see [this document]
Interoperability considerations: None.
Published specification: [this document]
Applications that use this media type: HTTP
Additional information:
Magic number(s): n/a
File extension(s): n/a
Macintosh file type code(s): n/a
Person & email address to contact for further information:
Mark Nottingham <mnot@mnot.net>
Intended usage: COMMON
Restrictions on usage: None.
Author: Mark Nottingham <mnot@mnot.net>
Change controller: IESG
]]></artwork></figure>
</section>
<section title="Acknowledgements">
<t>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).
</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc2616;
&rfc3986;
&rfc4627;
&rfc5987;
&rfc5988;
</references>
<!-- <references title="Informative References">
</references> -->
<!--
<section title="Non-Normative JSON Schema">
<t>This schema is non-normative, and will probably disappear unless JSON
Schema actually starts moving forward.</t>
<figure><artwork><![CDATA[
{
"description": "Problem Details",
"type": "object",
"properties": {
"describedby": {
"type": "string",
"required": "true",
"format": "uri"
},
"title": { "type": "string", required: true },
"detail": { "type": "string" }
}
}
]]></artwork></figure>
</section>
-->
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 15:00:17 |