Proxy-Status

The HTTP Proxy-Status response header reports how each proxy or intermediary in the delivery chain handled the request, using the Structured Fields syntax.

Table of Contents

Usage
Directives
Example
Takeaway
See also

Usage

When a response passes through one or more proxies, reverse proxies, or CDN nodes, understanding what happened at each hop is essential for debugging. The Proxy-Status header gives each intermediary a standardized way to report its processing outcome, including errors, status codes received from upstream, and implementation-specific details.

Each proxy in the chain appends its own entry to the header, listed in the order from origin to client (the response traversal direction). This is the same ordering convention used by Cache-Status and Via. Each entry starts with a proxy identifier followed by optional parameters describing the outcome.

The header uses Structured Fields for consistent, machine-parseable values. Platforms like Cloudflare and Fastly send this header in production responses.

Directives

error

A token parameter identifying the type of error encountered by the proxy. The specification defines a registry of error types including dns_timeout, dns_error, destination_not_found, destination_unavailable, connection_refused, connection_terminated, connection_timeout, connection_limit_reached, tls_protocol_error, tls_certificate_error, tls_alert_received, http_request_error, http_request_denied, http_response_incomplete, http_response_timeout, http_protocol_error, proxy_internal_error, proxy_configuration_error, and proxy_loop_detected, among others.

details

A string parameter providing human-readable context about the error or processing outcome. Proxies use this for implementation-specific information not covered by the standard error types. Common values include OS-level error names or internal status codes.

next-hop

A string or token parameter identifying the next-hop server the proxy selected for the request. This is the intermediary or origin the proxy forwarded the request to, useful for tracing the path through multi-tier infrastructure.

next-protocol

A token or byte sequence parameter identifying the ALPN protocol used to connect to the next-hop server. Common values include h2 (HTTP/2), h3 (HTTP/3), and http/1.1. Useful for diagnosing protocol negotiation issues across hops.

received-status

An integer parameter containing the HTTP status code received from the next-hop server. Present when the proxy successfully contacted the upstream server but the response status is relevant to the reported outcome.

Example

A Cloudflare proxy reporting an incomplete HTTP response from the origin server. The error parameter identifies the failure type, and the proxy name Cloudflare-Proxy identifies which intermediary encountered the problem.

Proxy-Status: Cloudflare-Proxy; error=http_response_incomplete

A proxy named esa reporting a connection refused error. The details parameter provides OS-level context about the failure, indicating the upstream server actively rejected the TCP connection.

Proxy-Status: esa; error=connection_refused; details=os_error

A TLS protocol error during the proxy's attempt to establish a secure connection with the upstream server. The details parameter points to an OS-level error as the root cause.

Proxy-Status: esa; error=tls_protocol_error; details=os_error

Multiple proxies reporting in sequence. The first proxy encountered a DNS error. The left-to-right ordering shows the request path through the infrastructure.

Proxy-Status: cdn-edge; error=dns_timeout, cdn-shield

Takeaway

The Proxy-Status header provides a standardized way for proxies and intermediaries to report request handling details, replacing ad hoc error pages and vendor-specific headers with a consistent, structured format.