Internet Engineering Task Force (IETF) M. Nottingham
Request for Comments: 7807 Akamai
Category: Standards Track E. Wilde
ISSN: 2070-1721 March 2016
Internet Engineering Task Force (IETF) M. Nottingham
Request for Comments: 7807 Akamai
Category: Standards Track E. Wilde
ISSN: 2070-1721 March 2016
Problem Details for HTTP APIs
HTTP API的问题详细信息
Abstract
摘要
This document defines a "problem detail" as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.
本文档将“问题详细信息”定义为在HTTP响应中携带机器可读的错误详细信息的一种方式，以避免为HTTP API定义新的错误响应格式。
Status of This Memo
关于下段备忘
This is an Internet Standards Track document.
这是一份互联网标准跟踪文件。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（IESG）批准出版。有关互联网标准的更多信息，请参见RFC 5741第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7807.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc7807.
Copyright Notice
版权公告
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2016 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本，并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3
3. The Problem Details JSON Object . . . . . . . . . . . . . . . 3
3.1. Members of a Problem Details Object . . . . . . . . . . . 5
3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6
4. Defining New Problem Types . . . . . . . . . . . . . . . . . 6
4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2. Predefined Problem Types . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6.1. application/problem+json . . . . . . . . . . . . . . . . 9
6.2. application/problem+xml . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
7.1. Normative References . . . . . . . . . . . . . . . . . . 11
7.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 14
Appendix B. Using Problem Details with Other Formats . . . . . . 15
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3
3. The Problem Details JSON Object . . . . . . . . . . . . . . . 3
3.1. Members of a Problem Details Object . . . . . . . . . . . 5
3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6
4. Defining New Problem Types . . . . . . . . . . . . . . . . . 6
4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2. Predefined Problem Types . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6.1. application/problem+json . . . . . . . . . . . . . . . . 9
6.2. application/problem+xml . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
7.1. Normative References . . . . . . . . . . . . . . . . . . 11
7.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 14
Appendix B. Using Problem Details with Other Formats . . . . . . 15
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
HTTP [RFC7230] status codes are sometimes not sufficient to convey enough information about an error to be helpful. While humans behind Web browsers can be informed about the nature of the problem with an HTML [W3C.REC-html5-20141028] response body, non-human consumers of so-called "HTTP APIs" are usually not.
HTTP[RFC7230]状态代码有时不足以传达有关错误的足够有用信息。虽然Web浏览器的用户可以了解HTML[W3C.REC-html5-20141028]响应体问题的本质，但所谓“HTTP API”的非用户用户通常不会。
This specification defines simple JSON [RFC7159] and XML [W3C.REC-xml-20081126] document formats to suit this purpose. They are designed to be reused by HTTP APIs, which can identify distinct "problem types" specific to their needs.
本规范定义了简单的JSON[RFC7159]和XML[W3C.REC-XML-20081126]文档格式，以满足此目的。它们被设计为被HTTP API重用，HTTP API可以识别特定于其需求的不同“问题类型”。
Thus, API clients can be informed of both the high-level error class (using the status code) and the finer-grained details of the problem (using one of these formats).
因此，可以将高级错误类（使用状态代码）和问题的更细粒度细节（使用这些格式之一）通知API客户机。
For example, consider a response that indicates that the client's account doesn't have enough credit. The 403 Forbidden status code might be deemed most appropriate to use, as it will inform HTTP-generic software (such as client libraries, caches, and proxies) of the general semantics of the response.
例如，考虑一个响应，表明客户的帐户没有足够的信用。403禁止状态代码可能被认为最适合使用，因为它将通知HTTP通用软件（如客户端库、缓存和代理）响应的一般语义。
However, that doesn't give the API client enough information about why the request was forbidden, the applicable account balance, or how to correct the problem. If these details are included in the
但是，这并没有向API客户端提供足够的信息，说明请求被禁止的原因、适用的帐户余额，或者如何更正问题。如果这些详细信息包含在
response body in a machine-readable format, the client can treat it appropriately; for example, triggering a transfer of more credit into the account.
响应体采用机器可读的格式，客户端可以对其进行适当处理；例如，触发向帐户转移更多信贷。
This specification does this by identifying a specific type of problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can do this by nominating new URIs under their control, or by reusing existing ones.
本规范通过使用URI[RFC3986]识别特定类型的问题（例如，“信用缺失”）来实现这一点；HTTP API可以通过指定其控制下的新URI或重用现有URI来实现这一点。
Additionally, problem details can contain other information, such as a URI that identifies the specific occurrence of the problem (effectively giving an identifier to the concept "The time Joe didn't have enough credit last Thursday"), which can be useful for support or forensic purposes.
此外，问题详细信息还可以包含其他信息，例如标识问题具体发生情况的URI（有效地为“Joe上周四没有足够信用的时间”这一概念提供了标识符），这些信息对于支持或取证目的非常有用。
The data model for problem details is a JSON [RFC7159] object; when formatted as a JSON document, it uses the "application/problem+json" media type. Appendix A defines how to express them in an equivalent XML format, which uses the "application/problem+xml" media type.
问题细节的数据模型是一个JSON[RFC7159]对象；当格式化为JSON文档时，它使用“application/problem+JSON”媒体类型。附录A定义了如何用等效的XML格式表示它们，该格式使用“application/problem+XML”媒体类型。
Note that problem details are (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 relevant details in that application's format. Likewise, in many situations, there is an appropriate HTTP status code that does not require extra detail to be conveyed.
请注意，问题细节（自然）不是在HTTP中传达问题细节的唯一方式；例如，如果响应仍然是一个资源的表示，则通常最好以该应用程序的格式描述相关细节。同样，在许多情况下，有一个适当的HTTP状态代码，不需要传达额外的细节。
Instead, the aim of this specification is to define common error formats for those applications that need one, so that they aren't required to define their own, or worse, tempted to redefine the semantics of existing HTTP status codes. Even if an application chooses not to use it to convey errors, reviewing its design can help guide the design decisions faced when conveying errors in an existing format.
相反，本规范的目的是为那些需要通用错误格式的应用程序定义通用错误格式，这样它们就不需要定义自己的错误格式，或者更糟糕的是，不需要重新定义现有HTTP状态代码的语义。即使应用程序选择不使用它来传递错误，检查其设计也可以帮助指导以现有格式传递错误时所面临的设计决策。
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 [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。
The canonical model for problem details is a JSON [RFC7159] object.
问题细节的规范模型是JSON[RFC7159]对象。
When serialized as a JSON document, that format is identified with the "application/problem+json" media type.
当序列化为JSON文档时，该格式用“application/problem+JSON”媒体类型标识。
For example, an HTTP response carrying JSON problem details:
例如，包含JSON问题详细信息的HTTP响应：
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
Here, the out-of-credit problem (identified by its type URI) indicates the reason for the 403 in "title", gives a reference for the specific problem occurrence with "instance", gives occurrence-specific details in "detail", and adds two extensions; "balance" conveys the account's balance, and "accounts" gives links where the account can be topped up.
这里，失信问题（由其类型URI标识）指示“标题”中403的原因，用“实例”给出具体问题发生的参考，用“细节”给出具体发生的细节，并添加两个扩展；“余额”表示帐户的余额，“帐户”提供了可以补足帐户的链接。
The ability to convey problem-specific extensions allows more than one problem to be conveyed. For example:
传达问题特定扩展的能力允许传达多个问题。例如：
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {
"name": "age",
"reason": "must be a positive integer"
},
{
"name": "color",
"reason": "must be 'green', 'red' or 'blue'"}
]
}
{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {
"name": "age",
"reason": "must be a positive integer"
},
{
"name": "color",
"reason": "must be 'green', 'red' or 'blue'"}
]
}
Note that this requires each of the subproblems to be similar enough to use the same HTTP status code. If they do not, the 207 (Multi-Status) [RFC4918] code could be used to encapsulate multiple status messages.
注意，这要求每个子问题足够相似，以使用相同的HTTP状态代码。如果没有，207（多状态）[RFC4918]代码可用于封装多个状态消息。
A problem details object can have the following members:
问题详细信息对象可以具有以下成员：
o "type" (string) - A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
o “类型”（字符串）-标识问题类型的URI引用[RFC3986]。本规范鼓励在取消引用时，为问题类型提供人类可读的文档（例如，使用HTML[W3C.REC-html5-20141028]）。如果此成员不存在，则假定其值为“大约：空白”。
o "title" (string) - A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
o “title”（string）——问题类型的简短、易读的摘要。除了为了本地化（例如，使用主动式内容协商；请参见[RFC7231]，第3.4节），它不应随着问题的出现而改变。
o "status" (number) - The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
o “状态”（编号）-源服务器为发生此问题而生成的HTTP状态代码（[RFC7231]，第6节）。
o "detail" (string) - A human-readable explanation specific to this occurrence of the problem.
o “详细信息”（字符串）-针对此问题的可读解释。
o "instance" (string) - A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
o “实例”（字符串）-一个URI引用，用于标识问题的具体发生情况。如果取消引用，它可能会或可能不会产生进一步的信息。
Consumers MUST use the "type" string as the primary identifier for the problem type; the "title" string is advisory and included only for users who are not aware of the semantics of the URI and do not have the ability to discover them (e.g., offline log analysis). Consumers SHOULD NOT automatically dereference the type URI.
消费者必须使用“类型”字符串作为问题类型的主要标识符；“title”字符串是建议性的，仅适用于不了解URI语义且无法发现URI的用户（例如，脱机日志分析）。使用者不应自动取消对类型URI的引用。
The "status" member, if present, is only advisory; it conveys the HTTP status code used for the convenience of the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly. See Section 5 for further caveats regarding its use.
“地位”成员（如有）仅为顾问；它传递为方便消费者而使用的HTTP状态代码。生成器必须在实际HTTP响应中使用相同的状态代码，以确保不理解此格式的通用HTTP软件仍能正常运行。有关其使用的更多注意事项，请参见第5节。
Consumers can use the status member to determine what the original status code used by the generator was, in cases where it has been changed (e.g., by an intermediary or cache), and when message bodies persist without HTTP information. Generic HTTP software will still use the HTTP status code.
消费者可以使用状态成员来确定生成器使用的原始状态代码是什么，如果它已被更改（例如，由中介或缓存更改），以及消息体在没有HTTP信息的情况下保持不变。通用HTTP软件仍将使用HTTP状态代码。
The "detail" member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.
“细节”成员（如果存在）应该专注于帮助客户纠正问题，而不是提供调试信息。
Consumers SHOULD NOT parse the "detail" member for information; extensions are more suitable and less error-prone ways to obtain such information.
消费者不应解析“细节”成员以获取信息；扩展是获取此类信息更合适、更不容易出错的方法。
Note that both "type" and "instance" accept relative URIs; this means that they must be resolved relative to the document's base URI, as per [RFC3986], Section 5.
注意，“类型”和“实例”都接受相对URI；这意味着它们必须根据[RFC3986]第5节的规定，相对于文档的基本URI进行解析。
Problem type definitions MAY extend the problem details object with additional members.
问题类型定义可以使用其他成员扩展问题详细信息对象。
For example, our "out of credit" problem above defines two such extensions -- "balance" and "accounts" to convey additional, problem-specific information.
例如，我们上面的“信用缺失”问题定义了两个这样的扩展——“余额”和“账户”来传递额外的、特定于问题的信息。
Clients consuming problem details MUST ignore any such extensions that they don't recognize; this allows problem types to evolve and include additional information in the future.
使用问题详细信息的客户必须忽略他们不认识的任何此类扩展；这使得问题类型得以发展，并在将来包含更多信息。
Note that because extensions are effectively put into a namespace by the problem type, it is not possible to define new "standard" members without defining a new media type.
请注意，由于问题类型有效地将扩展放入了命名空间中，因此在不定义新媒体类型的情况下，不可能定义新的“标准”成员。
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.
当HTTP API需要定义指示错误条件的响应时，可以通过定义新的问题类型来实现。
Before doing so, 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 itself. Designers of new problem types need to carefully consider the Security Considerations (Section 5), in particular, the risk of exposing attack vectors by exposing implementation internals through error messages.
问题详细信息不是底层实现的调试工具；相反，它们是公开HTTP接口本身更多细节的一种方式。新问题类型的设计者需要仔细考虑安全性考虑（第5节），特别是通过错误消息公开实现内部构件暴露攻击向量的风险。
Likewise, 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 probably unnecessary, since a 403 Forbidden status code in response to a PUT request is self-explanatory.
类似地，真正的通用问题——即可能应用于Web上任何资源的条件——通常最好用简单的状态代码表示。例如，“不允许写入访问”问题可能是不必要的，因为响应PUT请求的403禁止状态代码是不言自明的。
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 [RFC7231], Section 5.3.2).
也就是说，可以使用HTTP内容协商向现有HTTP API添加对问题细节的支持（例如，使用Accept请求头指示对此格式的偏好；请参阅[RFC7231]，第5.3.2节）。
New problem type definitions MUST document:
新问题类型定义必须记录：
1. a type URI (typically, with the "http" or "https" scheme),
1. 类型URI（通常使用“http”或“https”方案），
2. a title that appropriately describes it (think short), and
2. 适当描述它的标题（简而言之），以及
3. the HTTP status code for it to be used with.
3. 它要与一起使用的HTTP状态代码。
Problem type definitions MAY specify the use of the Retry-After response header ([RFC7231], Section 7.1.3) in appropriate circumstances.
问题类型定义可指定在适当情况下使用响应后重试标头（[RFC7231]，第7.1.3节）。
A problem's type URI SHOULD resolve to HTML [W3C.REC-html5-20141028] documentation that explains how to resolve the problem.
问题的类型URI应解析为解释如何解决问题的HTML[W3C.REC-html5-20141028]文档。
A problem type definition MAY specify additional members on the problem details object. For example, an extension might use typed links [RFC5988] to another resource that can be used by machines to resolve the problem.
问题类型定义可以指定问题详细信息对象上的其他成员。例如，扩展可能使用类型化链接[RFC5988]指向另一个资源，机器可以使用该资源来解决问题。
If such additional members are defined, their names SHOULD start with a letter (ALPHA, as per [RFC5234], Appendix B.1) and SHOULD consist of characters from ALPHA, DIGIT ([RFC5234], Appendix B.1), and "_" (so that it can be serialized in formats other than JSON), and they SHOULD be three characters or longer.
如果定义了此类附加成员，则其名称应以字母开头（根据[RFC5234]，附录B.1的规定，字母应为ALPHA），并由字母、数字（[RFC5234]，附录B.1）和“_”（以便可以以JSON以外的格式序列化）中的字符组成，且应为三个字符或更长。
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.
例如，如果要将HTTP API发布到在线购物车，则可能需要指出该用户没有信用（我们上面的示例），因此无法进行购买。
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 consider using one of the problem details formats -- JSON if your API is JSON-based, or XML if it uses that format.
如果您已经有一个特定于应用程序的格式可以容纳这些信息，那么最好这样做。但是，如果您不使用，您可能会考虑使用问题细节格式之一——如果您的API是JSON的，JSON，或者XML，如果使用该格式。
To do so, you might look for an already-defined type URI that suits your purposes. If one is available, you can reuse that URI.
为此，您可以寻找一个已经定义的适合您的目的的类型URI。如果有可用的URI，则可以重用该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.
如果一个URI不可用，您可以创建并记录一个新类型的URI（它应该在您的控制下并随着时间的推移保持稳定）、一个合适的标题和它将与之一起使用的HTTP状态代码，以及它的含义和应如何处理。
In summary: an instance URI will always identify a specific occurrence of a problem. On the other hand, type URIs can be reused if an appropriate description of a problem type is already available someplace else, or they can be created for new problem types.
总之：实例URI将始终标识问题的特定事件。另一方面，如果问题类型的适当描述在其他地方已经可用，或者可以为新的问题类型创建类型URI，则可以重用类型URI。
This specification reserves the use of one URI as a problem type:
本规范保留使用一个URI作为问题类型：
The "about:blank" URI [RFC6694], when used as a problem type, indicates that the problem has no additional semantics beyond that of the HTTP status code.
“about:blank”URI[RFC6694]用作问题类型时，表示问题除了HTTP状态代码之外没有其他语义。
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).
当使用“about:blank”时，标题应该与该代码的推荐HTTP状态短语相同（例如，404的“Not Found”等），尽管它可能会本地化以适应客户机偏好（用Accept Language请求标头表示）。
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.
请注意，根据“type”成员的定义（第3.1节），“about:blank”URI是该成员的默认值。因此，任何不携带显式“type”成员的问题细节对象都会隐式使用此URI。
When defining a new problem type, the information included must be carefully vetted. Likewise, when actually generating a problem -- however it is serialized -- the details given must also be scrutinized.
定义新问题类型时，必须仔细检查包含的信息。同样，当实际生成问题时——不管它是如何序列化的——也必须仔细检查给出的细节。
Risks include leaking information that can be exploited to compromise the system, access to the system, or the privacy of users of the system.
风险包括泄露信息，这些信息可被利用来危害系统、系统访问或系统用户的隐私。
Generators providing links to occurrence information are encouraged to avoid making implementation details such as a stack dump available through the HTTP interface, since this can expose sensitive details of the server implementation, its data, and so on.
建议提供事件信息链接的生成器避免通过HTTP接口提供实现细节，如堆栈转储，因为这可能会暴露服务器实现及其数据等的敏感细节。
The "status" member duplicates the information available in the HTTP status code itself, thereby bringing the possibility of disagreement between the two. Their relative precedence is not clear, since a disagreement might indicate that (for example) an intermediary has modified the HTTP status code in transit (e.g., by a proxy or cache).
“status”成员复制HTTP状态代码本身中可用的信息，从而带来两者之间不一致的可能性。它们的相对优先级不清楚，因为不一致可能表明（例如）中间人在传输过程中修改了HTTP状态代码（例如，通过代理或缓存）。
As such, those defining problem types as well as generators and consumers of problems need to be aware that generic software (such as proxies, load balancers, firewalls, and virus scanners) are unlikely to know of or respect the status code conveyed in this member.
因此，定义问题类型的人以及问题的产生者和消费者需要知道，通用软件（如代理、负载平衡器、防火墙和病毒扫描程序）不太可能知道或尊重此成员中传递的状态代码。
This specification defines two new Internet media types [RFC6838].
本规范定义了两种新的互联网媒体类型[RFC6838]。
Type name: application
类型名称：应用程序
Subtype name: problem+json
子类型名称：problem+json
Required parameters: None
所需参数：无
Optional parameters: None; unrecognized parameters should be ignored
可选参数：无；应忽略无法识别的参数
Encoding considerations: Same as [RFC7159]
编码注意事项：与[RFC7159]相同
Security considerations: see Section 5 of this document
安全注意事项：见本文件第5节
Interoperability considerations: None
互操作性注意事项：无
Published specification: RFC 7807 (this document)
已发布规范：RFC 7807（本文件）
Applications that use this media type: HTTP
使用此媒体类型的应用程序：HTTP
Fragment identifier considerations: Same as for application/json ([RFC7159])
片段标识符注意事项：与application/json相同（[RFC7159]）
Additional information:
其他信息：
Deprecated alias names for this type: n/a
此类型的已弃用别名：不适用
Magic number(s): n/a
Magic number(s): n/a
File extension(s): n/a
File extension(s): n/a
Macintosh file type code(s): n/a
Macintosh file type code(s): n/a
Person and email address to contact for further information:
Mark Nottingham <mnot@mnot.net>
Person and 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>
Author: Mark Nottingham <mnot@mnot.net>
Change controller: IESG
更改控制器：IESG
Type name: application
类型名称：应用程序
Subtype name: problem+xml
子类型名称：problem+xml
Required parameters: None
所需参数：无
Optional parameters: None; unrecognized parameters should be ignored
可选参数：无；应忽略无法识别的参数
Encoding considerations: Same as [RFC7303]
编码注意事项：与[RFC7303]相同
Security considerations: see Section 5 of this document
安全注意事项：见本文件第5节
Interoperability considerations: None
互操作性注意事项：无
Published specification: RFC 7807 (this document)
已发布规范：RFC 7807（本文件）
Applications that use this media type: HTTP
使用此媒体类型的应用程序：HTTP
Fragment identifier considerations: Same as for application/xml (as specified by Section 5 of [RFC7303])
片段标识符注意事项：与application/xml相同（如[RFC7303]第5节所述）
Additional information:
其他信息：
Deprecated alias names for this type: n/a
此类型的已弃用别名：不适用
Magic number(s): n/a
Magic number(s): n/a
File extension(s): n/a
File extension(s): n/a
Macintosh file type code(s): n/a
Macintosh file type code(s): n/a
Person and email address to contact for further information:
Mark Nottingham <mnot@mnot.net>
Person and 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>
Author: Mark Nottingham <mnot@mnot.net>
Change controller: IESG
更改控制器：IESG
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，DOI 10.17487/RFC2119，1997年3月<http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <http://www.rfc-editor.org/info/rfc3986>.
[RFC3986]Berners Lee，T.，Fielding，R.，和L.Masinter，“统一资源标识符（URI）：通用语法”，STD 66，RFC 3986，DOI 10.17487/RFC3986，2005年1月<http://www.rfc-editor.org/info/rfc3986>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <http://www.rfc-editor.org/info/rfc5234>.
[RFC5234]Crocker，D.，Ed.和P.Overell，“语法规范的扩充BNF:ABNF”，STD 68，RFC 5234，DOI 10.17487/RFC5234，2008年1月<http://www.rfc-editor.org/info/rfc5234>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7159]Bray，T.，Ed.“JavaScript对象表示法（JSON）数据交换格式”，RFC 7159，DOI 10.17487/RFC7159，2014年3月<http://www.rfc-editor.org/info/rfc7159>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.
[RFC7230]Fielding，R.，Ed.和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：消息语法和路由”，RFC 7230，DOI 10.17487/RFC7230，2014年6月<http://www.rfc-editor.org/info/rfc7230>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <http://www.rfc-editor.org/info/rfc7231>.
[RFC7231]Fielding，R.，Ed.和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：语义和内容”，RFC 7231，DOI 10.17487/RFC72312014年6月<http://www.rfc-editor.org/info/rfc7231>.
[W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", W3C Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[W3C.REC-xml-20081126]Bray，T.，Paoli，J.，Sperberg McQueen，M.，Maler，E.，和F.Yergeau，“可扩展标记语言（xml）1.0（第五版）”，W3C建议REC-xml-20081126，2008年11月<http://www.w3.org/TR/2008/REC-xml-20081126>.
[ISO-19757-2]
International Organization for Standardization,
"Information Technology --- Document Schema Definition
Languages (DSDL) --- Part 2: Grammar-based Validation ---
RELAX NG", ISO/IEC 19757-2, 2003.
[ISO-19757-2]
International Organization for Standardization,
"Information Technology --- Document Schema Definition
Languages (DSDL) --- Part 2: Grammar-based Validation ---
RELAX NG", ISO/IEC 19757-2, 2003.
[RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007, <http://www.rfc-editor.org/info/rfc4918>.
[RFC4918]Dusseault，L.，Ed.“Web分布式创作和版本控制（WebDAV）的HTTP扩展”，RFC 4918，DOI 10.17487/RFC4918，2007年6月<http://www.rfc-editor.org/info/rfc4918>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010, <http://www.rfc-editor.org/info/rfc5988>.
[RFC5988]诺丁汉，M.，“网络链接”，RFC 5988，DOI 10.17487/RFC5988，2010年10月<http://www.rfc-editor.org/info/rfc5988>.
[RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694, DOI 10.17487/RFC6694, August 2012, <http://www.rfc-editor.org/info/rfc6694>.
[RFC6694]Moonesay，S.，Ed.，“关于”URI方案“，RFC 6694，DOI 10.17487/RFC6694，2012年8月<http://www.rfc-editor.org/info/rfc6694>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <http://www.rfc-editor.org/info/rfc6838>.
[RFC6838]Freed，N.，Klensin，J.和T.Hansen，“介质类型规范和注册程序”，BCP 13，RFC 6838，DOI 10.17487/RFC6838，2013年1月<http://www.rfc-editor.org/info/rfc6838>.
[RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, DOI 10.17487/RFC7303, July 2014, <http://www.rfc-editor.org/info/rfc7303>.
[RFC7303]Thompson，H.和C.Lilley，“XML媒体类型”，RFC 7303，DOI 10.17487/RFC7303，2014年7月<http://www.rfc-editor.org/info/rfc7303>.
[W3C.REC-html5-20141028] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", W3C Recommendation REC-html5-20141028, October 2014, <http://www.w3.org/TR/2014/REC-html5-20141028>.
[W3C.REC-html5-20141028]希克森，I.，伯容，R.，福克纳，S.，莱塞德，T.，纳瓦拉，E.，奥康纳，E.，和S.普菲弗，“html5”，W3C建议REC-html5-20141028，2014年10月<http://www.w3.org/TR/2014/REC-html5-20141028>.
[W3C.REC-rdfa-core-20130822] Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa Core 1.1 - Second Edition", W3C Recommendation REC-rdfa-core-20130822, August 2013, <http://www.w3.org/TR/2013/REC-rdfa-core-20130822>.
[W3C.REC-rdfa-core-20130822]Adida，B.，Birbeck，M.，McCarron，S.，和I.Herman，“rdfa core 1.1-第二版”，W3C建议REC-rdfa-core-20130822，2013年8月<http://www.w3.org/TR/2013/REC-rdfa-core-20130822>.
[W3C.REC-xml-stylesheet-20101028] Clark, J., Pieters, S., and H. Thompson, "Associating Style Sheets with XML documents 1.0 (Second Edition)", W3C Recommendation REC-xml-stylesheet-20101028, October 2010, <http://www.w3.org/TR/2010/REC-xml-stylesheet-20101028>.
[W3C.REC-xml-stylesheet-20101028]Clark，J.，Pieters，S.，和H.Thompson，“将样式表与xml文档1.0相关联（第二版）”，W3C建议REC-xml-stylesheet-20101028，2010年10月<http://www.w3.org/TR/2010/REC-xml-stylesheet-20101028>.
Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary format convention. Such APIs can express problem details using the format defined in this appendix.
一些基于HTTP的API使用XML[W3C.REC-XML-20081126]作为其主要格式约定。此类API可以使用本附录中定义的格式表达问题细节。
The RELAX NG schema [ISO-19757-2] for the XML format is as follows. Keep in mind that this schema is only meant as documentation, and not as a normative schema that captures all constraints of the XML format. Also, it would be possible to use other XML schema languages to define a similar set of constraints (depending on the features of the chosen schema language).
XML格式的RELAXNG模式[ISO-19757-2]如下所示。请记住，此模式仅指文档，而不是捕获XML格式所有约束的规范模式。此外，还可以使用其他XML模式语言来定义一组类似的约束（取决于所选模式语言的特性）。
default namespace ns = "urn:ietf:rfc:7807"
default namespace ns = "urn:ietf:rfc:7807"
start = problem
start = problem
problem =
element problem {
( element type { xsd:anyURI }?
& element title { xsd:string }?
& element detail { xsd:string }?
& element status { xsd:positiveInteger }?
& element instance { xsd:anyURI }? ),
anyNsElement
}
problem =
element problem {
( element type { xsd:anyURI }?
& element title { xsd:string }?
& element detail { xsd:string }?
& element status { xsd:positiveInteger }?
& element instance { xsd:anyURI }? ),
anyNsElement
}
anyNsElement =
( element ns:* { anyNsElement | text }
| attribute * { text })*
anyNsElement =
( element ns:* { anyNsElement | text }
| attribute * { text })*
The media type for this format is "application/problem+xml".
此格式的媒体类型为“应用程序/问题+xml”。
Extension arrays and objects are serialized into the XML format by considering an element containing a child or children to represent an object, except for elements that contain only child element(s) named 'i', which are considered arrays. For example, the example above appears in XML as follows:
Extension arrays and objects are serialized into the XML format by considering an element containing a child or children to represent an object, except for elements that contain only child element(s) named 'i', which are considered arrays. For example, the example above appears in XML as follows:translate error, please retry
HTTP/1.1 403 Forbidden
Content-Type: application/problem+xml
Content-Language: en
HTTP/1.1 403 Forbidden
Content-Type: application/problem+xml
Content-Language: en
<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
<type>https://example.com/probs/out-of-credit</type>
<title>You do not have enough credit.</title>
<detail>Your current balance is 30, but that costs 50.</detail>
<instance>https://example.net/account/12345/msgs/abc</instance>
<balance>30</balance>
<accounts>
<i>https://example.net/account/12345</i>
<i>https://example.net/account/67890</i>
</accounts>
</problem>
<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
<type>https://example.com/probs/out-of-credit</type>
<title>You do not have enough credit.</title>
<detail>Your current balance is 30, but that costs 50.</detail>
<instance>https://example.net/account/12345/msgs/abc</instance>
<balance>30</balance>
<accounts>
<i>https://example.net/account/12345</i>
<i>https://example.net/account/67890</i>
</accounts>
</problem>
Note that this format uses an XML namespace. This is primarily to allow embedding it into other XML-based formats; it does not imply that it can or should be extended with elements or attributes in other namespaces. The RELAX NG schema explicitly only allows elements from the one namespace used in the XML format. Any extension arrays and objects MUST be serialized into XML markup using only that namespace.
请注意，此格式使用XML名称空间。这主要是为了将其嵌入到其他基于XML的格式中；这并不意味着它可以或应该在其他名称空间中使用元素或属性进行扩展。RELAXNG模式显式地只允许XML格式中使用的名称空间中的元素。必须仅使用该名称空间将任何扩展数组和对象序列化为XML标记。
When using the XML format, it is possible to embed an XML processing instruction in the XML that instructs clients to transform the XML, using the referenced XSLT code [W3C.REC-xml-stylesheet-20101028]. If this code is transforming the XML into (X)HTML, then it is possible to serve the XML format, and yet have clients capable of performing the transformation display human-friendly (X)HTML that is rendered and displayed at the client. Note that when using this method, it is advisable to use XSLT 1.0 in order to maximize the number of clients capable of executing the XSLT code.
使用XML格式时，可以使用引用的XSLT代码[W3C.REC-XML-stylesheet-20101028]在XML中嵌入XML处理指令，指示客户端转换XML。如果此代码正在将XML转换为（X）HTML，那么就可以为XML格式提供服务，并且客户机能够执行转换，显示在客户机上呈现和显示的人性化（X）HTML。请注意，在使用此方法时，建议使用XSLT1.0，以最大限度地增加能够执行XSLT代码的客户机数量。
In some situations, it can be advantageous to embed problem details in formats other than those described here. For example, an API that uses HTML [W3C.REC-html5-20141028] might want to also use HTML for expressing its problem details.
在某些情况下，将问题细节嵌入到本文所述格式以外的格式中可能是有利的。例如，使用HTML[W3C.REC-html5-20141028]的API可能也希望使用HTML来表达其问题细节。
Problem details can be embedded in other formats either by encapsulating one of the existing serializations (JSON or XML) into that format or by translating the model of a problem detail (as specified in Section 3) into the format's conventions.
通过将现有序列化（JSON或XML）之一封装为其他格式，或者将问题细节的模型（如第3节所述）转换为该格式的约定，可以将问题细节嵌入到其他格式中。
For example, in HTML, a problem could be embedded by encapsulating JSON in a script tag:
例如，在HTML中，可以通过将JSON封装在脚本标记中来嵌入问题：
<script type="application/problem+json">
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
</script>
<script type="application/problem+json">
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
</script>
or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20130822].
或者通过发明到RDFa的映射[W3C.REC-RDFa-core-20130822]。
This specification does not make specific recommendations regarding embedding problem details in other formats; the appropriate way to embed them depends both upon the format in use and application of that format.
本规范未就以其他格式嵌入问题细节提出具体建议；嵌入它们的适当方式取决于使用的格式和该格式的应用。
Acknowledgements
致谢
The authors would like to thank Jan Algermissen, Subbu Allamaraju, Mike Amundsen, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, Julian Reschke, and James Snell for review of this specification.
作者要感谢Jan Algermissen、Subbu Allamaraju、Mike Amundsen、Roy Fielding、Eran Hammer、Sam Johnston、Mike McCall、Julian Reschke和James Snell对本规范的审查。
Authors' Addresses
作者地址
Mark Nottingham Akamai
马克·诺丁汉Akamai
Email: mnot@mnot.net
URI: https://www.mnot.net/
Email: mnot@mnot.net
URI: https://www.mnot.net/
Erik Wilde
埃里克·王尔德
Email: erik.wilde@dret.net
URI: http://dret.net/netdret/
Email: erik.wilde@dret.net
URI: http://dret.net/netdret/