1. Introduction

1. Introduction

HTTP intermediaries (see Section 3.7 of [HTTP]) -- including both forward proxies and gateways (also known as "reverse proxies") -- have become an increasingly significant part of HTTP deployments. In particular, reverse proxies and content delivery networks (CDNs) form part of the critical infrastructure of many websites.

Typically, HTTP intermediaries forward requests towards the origin server (inbound) and then forward their responses back to clients (outbound). However, if an error occurs before a response is obtained from an inbound server, the response is often generated by the intermediary itself.

HTTP accommodates these types of errors with a few status codes -- for example, 502 (Bad Gateway) and 504 (Gateway Timeout). However, experience has shown that more information is necessary to aid debugging and communicate what's happened to the client. Additionally, intermediaries sometimes want to convey additional information about their handling of a response, even if they did not generate it.

To enable these uses, Section 2 defines a new HTTP response field to allow intermediaries to convey details of their handling of a response. Section 2.1 enumerates the information that can be added to the field by intermediaries, which can be extended per Section 2.2. Section 2.3 defines a set of error types for use when a proxy encounters an issue when obtaining a response for the request; these can likewise be extended per Section 2.4.

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: List, String, Token, Integer, and Byte Sequence.

Note that in this specification, "proxy" is used to indicate both forward and reverse proxies, otherwise known as gateways. "Next hop" indicates the connection in the direction leading to the origin server for the request.