RFC 9209 / START HERE
Proxy-Status, before the details
Proxy-Status is an HTTP response field. HTTP is Hypertext Transfer Protocol; a proxy is an intermediary that handles traffic between a client and another server.
It lets intermediaries describe how they handled a response, including problems obtaining it from the next server. A structured list records origin-side reports first and client-side reports last.
The idea in one picture
Handle response
Add hop report
Read with care
A simplified picture of the idea; the chapters explain the actual mechanisms.
Why it exists
A 502 or 504 status alone often does not explain which hop failed or why. This publication defines typed diagnostic parameters, error names and rules for late reports sent in trailers. It is separate from Cache-Status and does not change HTTP status semantics.
A familiar example
A fictional Edge proxy cannot open a connection to an origin. It generates a 504 with Proxy-Status: Edge; error=connection_timeout. That distinguishes a connection timeout from a DNS timeout. The field is optional and unverified; it is not proof of the network path or permission to retry.
Helpful background
You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.
What you’ll learn next
Begin with chapter one, or choose a topic.
- Follow the response pathA proxy is an intermediary: it handles HTTP between a client and the next server. Proxy-Status records response handling in a structured list.→
- Read typed parametersEach list member has an identifier plus optional semicolon parameters. Structured Fields assign types: Tokens are unquoted identifiers, Strings are quoted text, and Integers are whole numbers.→
- Locate the failureAn error parameter describes an intermediary’s problem obtaining the response. Some errors require a proxy-generated response; others can accompany an origin’s partial response.→
- Add a late trailerA trailer is a field sent after message content. A streaming proxy may learn about a failure only after its response headers have gone out.→
- Limit disclosure and trustDiagnostics can expose backend topology or sensitive deployment details. A readable Proxy-Status report is a claim by an intermediary, not independent proof.→
This introduction explains RFC 9209 (2022). Read the original RFC ↗