1. 简介

HTTP [RFC7230] 状态码有时不足以传达足够多的错误信息, 因而无法提供帮助. 虽然 Web 浏览器背后的人类用户可以通过 HTML [W3C.REC-html5-20141028] 响应体了解问题性质, 但所谓 "HTTP API" 的非人类消费者通常不能.

本规范定义了简单的 JSON [RFC7159] 和 XML [W3C.REC-xml-20081126] 文档格式来满足这一目的. 它们设计为可被 HTTP API 复用, API 可以识别符合自身需求的不同 "problem types".

因此, API 客户端既可以获知高级别错误类别 (使用状态码), 也可以获知问题的更细粒度详情 (使用这些格式之一).

例如, 考虑一个表示客户端账户余额不足的响应. 403 Forbidden 状态码可能被认为最合适, 因为它会向通用 HTTP 软件 (例如客户端库、缓存和代理) 说明该响应的一般语义.

但是, 这并不能向 API 客户端提供足够信息, 说明请求为什么被禁止、适用的账户余额是多少, 或如何纠正该问题. 如果这些详情以机器可读格式包含在响应体中, 客户端就可以适当处理它; 例如, 触发向账户转入更多额度.

本规范通过使用 URI [RFC3986] 标识特定问题类型 (例如 "out of credit") 来做到这一点; HTTP API 可以通过指定其控制下的新 URI 或复用现有 URI 来实现.

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

问题详情的数据模型是一个 JSON [RFC7159] 对象; 当格式化为 JSON 文档时, 它使用 "application/problem+json" 媒体类型. 附录 A 定义了如何用等价的 XML 格式表达它们, 该格式使用 "application/problem+xml" 媒体类型.

注意, 问题详情自然不是在 HTTP 中传达问题详情的唯一方式; 例如, 如果响应仍然是某个资源的表示, 通常更适合在该应用自己的格式中描述相关详情. 同样, 在许多情况下, 也存在不需要传达额外详情的适当 HTTP 状态码.

因此, 本规范的目标是为需要通用错误格式的应用定义这种格式, 使它们不必自行定义, 更糟糕的情况是被诱使重新定义现有 HTTP 状态码的语义. 即便某个应用选择不使用它来传达错误, 审查其设计也有助于指导在现有格式中传达错误时面临的设计决策.