1. 简介 (Introduction)

HTTP 状态码 ([HTTP] Section 15) 并不总是能够传达足够有用的错误信息. 使用 Web 浏览器的人类用户通常可以理解 HTML [HTML5] 响应内容, 但 HTTP API 的非人类消费者很难做到这一点.

为解决这一不足, 本规范定义了简单的 JSON [JSON] 和 XML [XML] 文档格式, 用于描述所遇问题的具体情况, 即 "problem details".

例如, 考虑一个表示客户端账户余额不足的响应. API 设计者可能决定使用 403 Forbidden 状态码, 向通用 HTTP 软件 (例如客户端库、缓存和代理) 告知该响应的一般语义. API 特定的问题详情 (例如服务器为何拒绝请求以及适用的账户余额) 可以在响应内容中携带, 以便客户端能够据此采取适当行动 (例如触发向账户转入更多额度).

本规范使用 URI [URI] 标识具体的 "problem type" (例如 "out of credit"). HTTP API 可以使用由其控制的 URI 标识特定于自身的问题, 也可以重用现有 URI 以促进互操作性并利用通用语义 (见 Section 4.2).

问题详情可以包含其他信息, 例如标识问题特定发生实例的 URI (实际上是为 "Joe 上周四余额不足的那一次" 这一概念提供标识符), 这对支持或取证目的可能有用.

问题详情的数据模型是 JSON [JSON] 对象; 当序列化为 JSON 文档时, 它使用 "application/problem+json" 媒体类型. Appendix B 定义了等价的 XML 格式, 该格式使用 "application/problem+xml" 媒体类型.

当问题详情在 HTTP 响应中传递时, 其内容可以使用主动协商 (proactive negotiation) 进行协商; 见 [HTTP] Section 12.1. 特别是, 人类可读字符串 (例如 title 和 description 中的字符串) 所使用的语言可以使用 Accept-Language 请求头字段 ([HTTP] Section 12.5.4) 进行协商, 尽管该协商仍可能返回非首选的默认表示.

问题详情可以与任何 HTTP 状态码一起使用, 但它们最自然地契合 4xx 和 5xx 响应的语义. 注意, 问题详情自然不是在 HTTP 中传达问题细节的唯一方式. 例如, 如果响应仍然是某个资源的表示, 通常最好使用该应用程序的格式描述相关细节. 同样, 已定义的 HTTP 状态码覆盖了许多无需传达额外细节的情况.

本规范的目标是为需要通用错误格式的应用程序定义这种格式, 使它们不必定义自己的格式, 更不会被诱导去重新定义现有 HTTP 状态码的语义. 即使应用程序选择不使用它来传达错误, 审阅其设计也有助于指导在现有格式中传达错误时面临的设计决策.

相对于 [RFC7807] 的变更列表见 Appendix D.