Network Working Group M. Nottingham Internet-Draft Cloudflare Intended status: Standards Track 30 October 2026 Expires: 3 May 2027 The Problem-Details HTTP Header Field draft-nottingham-problem-header-00 Abstract This specification defines the Problem-Details HTTP header field, which carries a problem details object (RFC 9457) as a Structured Field. Because the Structured Fields data model is more constrained than JSON's, it also defines a profile that problem types can opt into so that they can be serialised as a header. About This Document This note is to be removed before publishing as an RFC. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-nottingham-problem-header/. information can be found at https://projects.mnot.net/I-D/. Source for this draft and an issue tracker can be found at https://github.com/mnot/I-D/labels/problem-header. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 3 May 2027. Nottingham Expires 3 May 2027 [Page 1] Internet-Draft Problem-Details Header October 2026 Copyright Notice Copyright (c) 2026 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 (https://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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 2. The Problem-Details Header Field . . . . . . . . . . . . . . 3 3. Header-Compatible Problem Types . . . . . . . . . . . . . . . 5 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 6. Normative References . . . . . . . . . . . . . . . . . . . . 6 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction Problem details [PROBLEM] give HTTP APIs a common way to describe an error, but only in a message's content, as JSON [JSON] or XML. That is not always available. A response to a HEAD request has no content; a response whose content is a representation of the resource cannot also carry problem details; and an intermediary that generates or annotates an error might not be able to alter the content it forwards. This specification defines the "Problem-Details" response header field (Section 2) to carry problem details as a Structured Field [STRUCTURED-FIELDS]. Structured Fields cannot represent the entire JSON data model, so not every problem details object can be carried in the field. Section 3 defines a profile of problem details -- _header-compatible problem types_ -- to enable problem types to opt into being carried as HTTP header fields. Problem types that do not opt in to that profile can still be conveyed using the field, but the header field will only carry the members defined in [PROBLEM]. Nottingham Expires 3 May 2027 [Page 2] Internet-Draft Problem-Details Header October 2026 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. This document uses the following terminology from Section 3 of [STRUCTURED-FIELDS] to specify syntax and parsing: Dictionary, Inner List, Integer, Decimal, String, Token, Boolean, Parameters, Byte Sequence, Date, and Display String. It uses "problem details object", "problem type" and "extension member" as defined in [PROBLEM]. 2. The Problem-Details Header Field The "Problem-Details" response header field conveys a problem details object [PROBLEM]. Its value is a Dictionary. Each member of the Dictionary corresponds to the member of the problem details object with the same name, and has the Structured Type shown in Table 1. +==========+=================+==========================+ | Member | Structured Type | JSON type | +==========+=================+==========================+ | type | String | string (a URI reference) | +----------+-----------------+--------------------------+ | status | Integer | number | +----------+-----------------+--------------------------+ | title | Display String | string | +----------+-----------------+--------------------------+ | detail | Display String | string | +----------+-----------------+--------------------------+ | instance | String | string (a URI reference) | +----------+-----------------+--------------------------+ Table 1: Problem Details Members in the Problem- Details Field The semantics of the members are as defined in Section 3.1 of [PROBLEM]. A member whose value is not of the type shown in Table 1 is ignored, as in Section 3.1 of [PROBLEM]. Nottingham Expires 3 May 2027 [Page 3] Internet-Draft Problem-Details Header October 2026 A sender MAY omit any member, including type, which then has its default value of "about:blank". However, a sender MUST NOT include extension members unless it includes type. HTTP responses already carry a status code, so status is redundant in the field; senders SHOULD omit it. Any problem type can be conveyed with the field, using the members in Table 1. Extension members are carried only if the problem type is header-compatible (Section 3) and identifies them as carried in the field; a sender MUST NOT include any others. Recipients MUST ignore members they do not recognise, and any Parameters on members. For example, this response carries the out-of-credit problem from Section 3 of [PROBLEM], which we assume is header-compatible, with balance an Integer and accounts an Inner List of Strings: HTTP/1.1 403 Forbidden Problem-Details: 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") It is equivalent to this problem details object: { "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"] } A response can carry the field with or without problem details content. When it carries both, the field is a subset of the content. A recipient that finds a member with different values uses the content's value. Nottingham Expires 3 May 2027 [Page 4] Internet-Draft Problem-Details Header October 2026 3. Header-Compatible Problem Types A problem type is header-compatible if its definition says so and identifies which of its extension members are carried in the field. Only the party that defines a problem type can make it header- compatible; a recipient does not infer it from the members a response carries. Each of those members conforms to the following: * Its name begins with a lower-case letter, followed by lower-case letters, digits, "_", "-" or ".". This is a subset of the keys that Section 4.1.1.3 of [STRUCTURED-FIELDS] allows for a Dictionary member, chosen so that the name is also valid in the XML format (Section 3.2 of [PROBLEM]). * Its value is a boolean, number or string, or an array of them. It is not null or an object, and an array does not contain arrays. * The definition specifies the Structured Type of the member, as in Table 2. Where the value is an array, it specifies the type of the array's items. +=================+===========+===============================+ | Structured Type | JSON type | Constraints | +=================+===========+===============================+ | Integer | number | an integer; see Section 3.3.1 | | | | of [STRUCTURED-FIELDS] | +-----------------+-----------+-------------------------------+ | Decimal | number | at most 12 integer digits and | | | | 3 fractional digits | +-----------------+-----------+-------------------------------+ | String | string | ASCII characters only | +-----------------+-----------+-------------------------------+ | Token | string | conforms to the syntax of a | | | | Token | +-----------------+-----------+-------------------------------+ | Display String | string | any Unicode scalar value | +-----------------+-----------+-------------------------------+ | Boolean | boolean | | +-----------------+-----------+-------------------------------+ | Inner List | array | items are of the types above | +-----------------+-----------+-------------------------------+ Table 2: Mapping Between Structured Types and JSON Members of other Structured Types (Byte Sequence and Date) are ignored. Nottingham Expires 3 May 2027 [Page 5] Internet-Draft Problem-Details Header October 2026 A sender MUST use the Structured Type that the problem type specifies for each member. A recipient converts a String, Token or Display String to a JSON string, and an Integer or Decimal to a JSON number, without checking which the problem type specifies. A member of any other type, such as a Byte Sequence or Date, is ignored. The language of Display Strings is indicated by the Content-Language header field (Section 8.5 of [HTTP]), when present. 4. IANA Considerations IANA is asked to update the "Hypertext Transfer Protocol (HTTP) Field Name Registry" as follows: +=================+===========+=================+===========+ | Field Name | Status | Structured Type | Reference | +=================+===========+=================+===========+ | Problem-Details | permanent | Dictionary | Section 2 | +-----------------+-----------+-----------------+-----------+ Table 3 5. Security Considerations The considerations in Section 5 of [PROBLEM] apply to problem details using the field in the same way that they do to problem details in content: it is easy to leak implementation details through error messages. Because a header field is visible to, and often logged by, every intermediary on the path, senders should consider not only the impact of individual disclosures, but also what information might be gathered over time by observing many responses. Display Strings can contain any Unicode scalar value, including control characters. Recipients that display title, detail or a Display String extension member need to treat it as untrusted text, and filter or escape it first (Section 6 of [STRUCTURED-FIELDS]). Recipients SHOULD NOT automatically dereference the type or instance URIs (Section 3.1 of [PROBLEM]). Header fields are subject to size limits that content generally is not, and some implementations impose them on the whole header section. Senders that need to convey more than a small amount of information should use content or selectively omit members from the field. 6. Normative References Nottingham Expires 3 May 2027 [Page 6] Internet-Draft Problem-Details Header October 2026 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [STRUCTURED-FIELDS] Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024, . Author's Address Mark Nottingham Cloudflare Melbourne Australia Email: mnot@mnot.net URI: https://mnot.net/ Nottingham Expires 3 May 2027 [Page 7]