Skip to main content

2. The Proxy-Status HTTP Field

2. The Proxy-Status HTTP Field​

The Proxy-Status HTTP response field allows an intermediary to convey additional information about its handling of a response and its associated request.

Its value is a List (see Section 3.1 of [STRUCTURED-FIELDS]). Each member of the List represents an intermediary that has handled the response. The first member represents the intermediary closest to the origin server, and the last member represents the intermediary closest to the user agent.

For example:

Proxy-Status: revproxy1.example.net, ExampleCDN

indicates that this response was handled first by revproxy1.example.net (a reverse proxy adjacent to the origin server) and then ExampleCDN.

Intermediaries determine when it is appropriate to add the Proxy-Status field to a response. Some might decide to append it to all responses, whereas others might only do so when specifically configured to or when the request contains a header field that activates a debugging mode.

Each member of the List identifies the intermediary that inserted the value and MUST have a type of either String or Token. Depending on the deployment, this might be a service name (but not a software or hardware product name; e.g., "ExampleCDN" is appropriate, but "ExampleProxy" is not because it doesn't identify the deployment), a hostname ("proxy-3.example.com"), an IP address, or a generated string.

Parameters of each member (per Section 3.1.2 of [STRUCTURED-FIELDS]) convey additional information about that intermediary's handling of the response and its associated request; see Section 2.1. While all of these parameters are OPTIONAL, intermediaries are encouraged to provide as much information as possible (but see Section 4 for security considerations in doing so).

When adding a value to the Proxy-Status field, intermediaries SHOULD preserve the existing members of the field to allow debugging of the entire chain of intermediaries handling the request unless explicitly configured to remove them (e.g., to prevent internal network details from leaking; see Section 4).

Origin servers MUST NOT generate the Proxy-Status field.

Proxy-Status MAY be sent as an HTTP trailer field. For example, if an intermediary is streaming a response and the inbound connection suddenly terminates, Proxy-Status can only be appended to the trailer section of the outbound message since the header section has already been sent. However, because it might be silently discarded along the path to the user agent (as is the case for all trailer fields; see Section 6.5 of [HTTP]), Proxy-Status SHOULD NOT be sent as a trailer field unless it is not possible to send it in the header section.

To allow recipients to reconstruct the relative ordering of Proxy-Status members conveyed in trailer fields with those conveyed in header fields, an intermediary MUST NOT send Proxy-Status as a trailer field unless it has also generated a Proxy-Status header field with the same member (although potentially different parameters) in that message.

For example, a proxy identified as 'ThisProxy' that receives a response bearing a header field:

Proxy-Status: SomeOtherProxy

would add its own entry to the header field:

Proxy-Status: SomeOtherProxy, ThisProxy

thus allowing it to append a trailer field:

Proxy-Status: ThisProxy; error=read_timeout

which would thereby allow a downstream recipient to understand that processing by 'SomeOtherProxy' occurred before 'ThisProxy'.

A client MAY promote the Proxy-Status trailer field value to being in the header section for debugging or other purposes (e.g., making it easier to access).

2.1. Proxy-Status Parameters​

Each member of the Proxy-Status List can have parameters that describe the proxy's handling of the response. This section details those parameters.

2.1.1. error​

The "error" parameter has a value of type Token that is a Proxy Error Type (Section 2.3); its presence indicates that the intermediary encountered an issue when obtaining a response for the request.

2.1.2. next-hop​

The "next-hop" parameter has a value of type String or Byte Sequence; its presence indicates the next hop that the intermediary used to forward the request. This might be an IP address and port number, a hostname, or some other form of identifier.

2.1.3. next-protocol​

The "next-protocol" parameter has a value of type Token or Byte Sequence; its presence indicates the ALPN protocol identifier [RFC7301] used by the intermediary to connect to the next hop.

2.1.4. received-status​

The "received-status" parameter has a value of type Integer; its presence indicates the HTTP status code received by the intermediary from the next hop server. The parameter's value MUST be in the range 100-999 inclusive.

This parameter is only applicable when the error parameter is not present. It is intended to be used when the intermediary generates its own response based on the response received from the next hop, but it does not generate an error.

2.1.5. details​

The "details" parameter has a value of type String; its presence allows the proxy to convey additional information that is specific to this response and does not have a better-suited parameter. This might include implementation-specific or deployment-specific information.

2.2. Defining New Proxy-Status Parameters​

New Proxy-Status parameters can be defined by registering them in the "HTTP Proxy-Status Parameters" registry.

Registration requests are reviewed and approved by Expert Review, per [RFC8126], Section 4.5. A specification document is appreciated but not required.

The expert(s) should consider the following factors when evaluating requests:

  • Community feedback
  • If the value is sufficiently well-defined
  • Generic parameters are preferred over vendor-specific, application-specific, or deployment-specific values. If a generic value cannot be agreed upon in the community, the parameter's name should be correspondingly specific (e.g., with a prefix that identifies the vendor, application, or deployment).
  • If the parameter's name conflicts with or causes confusion with other Proxy-Status parameters, new or existing error types, or has the potential to do so in the future.

Registration requests should use the following template:

Name: [a name for the Proxy-Status parameter that is of type Token]

Description: [a description of the parameter's semantics]

Reference: [to a specification defining this parameter; optional]

Notes: [optional]

See the registry at https://www.iana.org/assignments/http-proxy-status for details on where to send registration requests.

Last updated on