Problem Details for HTTP APIs
RFC 7807
Document | Type | RFC - Proposed Standard (March 2016; Errata) | |
---|---|---|---|
Authors | Mark Nottingham , Erik Wilde | ||
Last updated | 2020-05-19 | ||
Replaces | draft-nottingham-http-problem | ||
Stream | Internent Engineering Task Force (IETF) | ||
Formats | plain text html pdf htmlized (tools) htmlized with errata bibtex | ||
Reviews | |||
Stream | WG state | Submitted to IESG for Publication | |
Document shepherd | Murray Kucherawy | ||
Shepherd write-up | Show (last changed 2015-11-20) | ||
IESG | IESG state | RFC 7807 (Proposed Standard) | |
Action Holders |
(None)
|
||
Consensus Boilerplate | Yes | ||
Telechat date | |||
Responsible AD | Barry Leiba | ||
Send notices to | "Murray Kucherawy" <superuser@gmail.com> | ||
IANA | IANA review state | Version Changed - Review Needed | |
IANA action state | RFC-Ed-Ack |
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 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. 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. 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. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. 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. Nottingham & Wilde Standards Track [Page 1] RFC 7807 Problem Details March 2016 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 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. 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. 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). 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. 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 Nottingham & Wilde Standards Track [Page 2] RFC 7807 Problem Details March 2016 response body in a machine-readable format, the client can treat it appropriately; for example, triggering a transfer of more credit into the account.Show full document text