The Proxy-Status HTTP Response Header Field
Extracted elements (28)
HTTP's existing error status codes (502, 504) were found insufficient for debugging intermediary failures in practice. Proxy-Status was introduced to let intermediaries convey structured, machine-readable details about error conditions and response handling — including when no response was obtained from the origin at all — without requiring changes to the status code semantics.
The Proxy-Status List is ordered with the intermediary closest to the origin first and the one closest to the user agent last, mirroring the natural inbound-to-outbound flow of the proxy chain. This ordering was chosen so that appending a new entry is a simple list append, and the full chain can be reconstructed in request-processing order.
Because trailer fields may be silently discarded along the path to the user agent (per HTTP semantics), Proxy-Status in a trailer is only reliable in environments where trailer support is guaranteed end-to-end. Clients that wish to use trailer-conveyed Proxy-Status data may promote it into the header field by matching trailer members to existing header members and replacing in place.
The 'next-protocol' parameter uses ALPN protocol identifiers to name the protocol used toward the next hop, but the value may not have been used in actual ALPN negotiation — it identifies the protocol in use, not the negotiation mechanism. Implementors must not infer that ALPN was performed based solely on this parameter's presence.
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 (though potentially different parameters) in that message. This allows recipients to reconstruct the relative ordering of members from both sections.
Each member of the Proxy-Status List MUST have a type of either String or Token. Deployment-appropriate identifiers include service names, hostnames, IP addresses, or generated strings; product names (e.g., 'ExampleProxy') are not appropriate because they do not identify the specific deployment.
Each proxy error type has a recommended HTTP status code; when generating a response containing the error, its status code SHOULD be set to that recommended value. Another status code may be used for backwards compatibility or when a status code has already been sent.
Origin servers MUST NOT generate the Proxy-Status field; only intermediaries are permitted to add it.
Proxy-Status SHOULD NOT be sent as a trailer field unless it is not possible to send it in the header section, because trailer fields may be silently discarded along the path to the user agent.
Unrecognized Proxy-Status parameters MUST be ignored by recipients.
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, unless explicitly configured to remove them (e.g., to prevent internal network details from leaking).
When sending the error parameter, the most specific proxy error type SHOULD be sent, provided it accurately represents the error condition. Generic types such as proxy_internal_error or http_protocol_error are available as fallbacks.
The 'connection_terminated' proxy error type (recommended HTTP 502) indicates the connection to the next hop was closed before a complete response was received. Its 'Response Only Generated by Intermediaries' flag is false, meaning it can appear on partially forwarded origin responses (e.g., as a trailer).
The 'details' parameter is a String containing implementation- or deployment-specific information not captured by other parameters. For example: 'details="Malformed response header: space before colon"'.
The 'dns_error' proxy error type (recommended HTTP 502) carries two extra parameters: 'rcode' (a String conveying the DNS RCODE per RFC 8499 §3) and 'info-code' (an Integer conveying the Extended DNS Error Code INFO-CODE per RFC 8914). It is only generated by intermediaries.
The 'error' parameter carries a Token value that is a proxy error type, indicating the intermediary encountered an issue obtaining the response. Error types with 'Response only generated by intermediaries: true' can only appear in responses synthesized by the proxy; 'false' types may accompany partial origin responses (e.g., appended as a trailer when a forward connection abruptly closes).
The 'http_request_error' proxy error type (recommended HTTP 4xx) indicates the intermediary is generating a client error response on the origin's behalf. Extra parameters include 'status-code' (Integer) and 'status-phrase' (String). It is exclusively generated by intermediaries and helps distinguish proxy-generated 4xx responses from origin-generated ones.
The 'next-hop' parameter is a String or Token identifying the intermediary or origin server selected (and used, if contacted) to obtain the response. Its value may be a hostname, IP address, or alias; e.g., 'next-hop=backend.example.org:8001'.
The 'next-protocol' parameter indicates the ALPN protocol identifier (RFC 7301) used by the intermediary to connect to the next hop. Its value MUST be either a Token or Byte Sequence representing a TLS ALPN Protocol ID; if expressible as an ASCII Token, that form MUST be used.
The 'proxy_loop_detected' proxy error type (recommended HTTP 502) indicates the intermediary tried to forward the request to itself or detected a loop via other means (e.g., RFC 8586). It is exclusively generated by intermediaries.
The Proxy-Status HTTP response field is a Structured Fields List where each member represents an intermediary that handled the response. The first member is the intermediary closest to the origin server; the last is closest to the user agent. Members are String or Token values identifying the intermediary (e.g., a service name, hostname, or IP address), with optional parameters conveying additional handling details.
The 'received-status' parameter conveys the HTTP status code the intermediary received from the next-hop server. Its value MUST be an Integer (e.g., 'received-status=200').
The 'tls_alert_received' proxy error type (recommended HTTP 502) carries 'alert-id' (an Integer from the TLS Alerts registry) and 'alert-message' (a Token or String with the description string). It is not exclusively generated by intermediaries, as the alert comes from the next hop.
IANA added 'Proxy-Status' as a permanent entry in the 'Hypertext Transfer Protocol (HTTP) Field Name Registry', with RFC 9209 as the specification document.
IANA created the 'HTTP Proxy Error Types' registry at https://www.iana.org/assignments/http-proxy-status, initially populated with the 32 error types defined in Section 2.3. New entries require Expert Review per RFC 8126 §4.5; each entry includes Name, Description, Extra Parameters, Recommended HTTP Status Code, Response Only Generated by Intermediaries flag, Reference, and optional Notes.
IANA created the 'HTTP Proxy-Status Parameters' registry at https://www.iana.org/assignments/http-proxy-status, initially populated with the parameters defined in Section 2.1 (error, next-hop, next-protocol, received-status, details). New entries require Expert Review per RFC 8126 §4.5.
A primary security concern is information leakage: Proxy-Status can expose intermediary configuration and backend topology, allowing attackers to directly target backend services unprepared for high traffic or malformed inputs. Intermediaries are not required to generate the field and may conditionally emit it based on request attributes such as authentication tokens or IP address.
The content of the Proxy-Status field is not verified; an intermediary can claim certain actions (e.g., sending a request over an encrypted channel) without actually performing them. Recipients cannot rely on Proxy-Status values as trustworthy attestations.