Proxy-Status is an HTTP response header that helps you understand what happened inside an intermediary like a CDN, reverse proxy, gateway, or corporate proxy. If a request “just feels slow,” fails mid-stream, or returns a generic 5xx, Proxy-Status can add the missing context you need to pinpoint whether the problem occurred at the origin or somewhere in the proxy layer. This guide breaks down what Proxy-Status means, how to read typical values, where it fits in debugging and performance analysis, and what to watch out for when you roll it out. Proxy-Status is an HTTP response header that lets an intermediary (a proxy, gateway, or CDN) report how it handled the response back to the client. In practice, it can describe events like “served from cache,” “upstream connection dropped,” or “DNS lookup failed,” making it easier for clients and operators to isolate the real failure point. Key takeaway: Proxy-Status describes what happened at the proxy/intermediary—not the health or state of your origin server. The header is standardized by the IETF. Proxy-Status Header Explained: Meaning, Syntax, and Use Cases
What is Proxy-Status?
Why use it?
Proxy-Status is mainly useful for incident troubleshooting and performance analysis. Even when a client only sees “it’s slow” or “it disconnected,” Proxy-Status can reveal what happened at a hop in the middle.
Faster root cause isolation
- Did a corporate proxy fail authentication or upstream connectivity?
- Could the CDN not reach the origin?
- Did a proxy terminate a streaming response mid-flight?
Stronger operational logs
Because the signal arrives as a response header, you can record it in client-side logs (browser apps, mobile apps, crawlers, API clients). That makes post-incident analysis much easier—especially for issues that don’t reproduce on demand.
Header format
Proxy-Status is made of one or more entries, each representing an intermediary, plus a set of parameters describing what happened. The exact parameters you’ll see depend on the product and configuration, but the core reading strategy stays the same: which proxy reported the status, and what did it say happened?
Note: RFC 9209 defines the overall framework and some standardized parameters (like error), but real-world output varies by CDN/proxy vendor and by deployment. Always cross-check with your proxy/CDN documentation.
Examples
These are simplified examples to make the format easier to recognize.
HTTP/1.1 200 OK
Proxy-Status: edge-proxy; ok
Content-Type: application/jsonHTTP/1.1 502 Bad Gateway
Proxy-Status: edge-proxy; error="dns_failure"
Content-Type: text/htmlIn the second example, the surface-level status is 502, but Proxy-Status suggests the proxy encountered a DNS resolution issue. (The precise error taxonomy and wording are implementation-dependent; RFC 9209 standardizes the concept and registers error types.)
RFC 9209 explains that if an intermediary’s status changes after it has already sent the response headers (for example, during streaming), it may attach Proxy-Status as a trailer field.
Practical usage examples
Check with curl
Start by confirming whether Proxy-Status appears in the response headers.
curl -sS -D - https://example.com/ -o /dev/nullLog it in your application
For API clients and crawlers, logging Proxy-Status alongside the HTTP status code makes network and proxy-layer failures much easier to diagnose later.
import requests
r = requests.get("https://example.com/api", timeout=10)
proxy_status = r.headers.get("Proxy-Status")
print("status=", r.status_code, "proxy_status=", proxy_status)Use it for monitoring and alerts
You can alert on patterns like “a specific Proxy-Status error exceeds N occurrences.” Even when everything looks like “5xx,” Proxy-Status can separate likely causes (DNS vs connect vs timeout vs caching behavior), which speeds up triage and reduces guesswork.
How it differs from other headers
Several headers are “proxy-related,” but they serve different goals. Don’t treat them as interchangeable.
| Header | Direction | Primary purpose | How to think about trust |
|---|---|---|---|
| Proxy-Status | Response | Conveys the proxy’s handling result and/or errors | Assumes the intermediary on-path adds it. Design your edge so off-path injection isn’t possible. |
| X-Forwarded-For | Request | Conveys forwarding info like client IP | Clients can spoof it unless you enforce a trust boundary and sanitize/overwrite at the edge. |
| Via | Request/Response | Shows which intermediaries the message passed through | Great for path visibility, but it’s not designed to express detailed failure reasons. |
Deployment cautions
Watch for information disclosure
Proxy-Status can reveal operational details (failure modes, upstream dependencies, or hints about internal architecture). Decide what level of detail is acceptable to expose externally. It may be perfect for internal APIs, but too revealing for a public-facing website.
Plan for multi-proxy environments
In stacked architectures (CDN → WAF → load balancer → reverse proxy), decide which layers add Proxy-Status, whether multiple entries should appear, and whether downstream components preserve or overwrite upstream values. Align logging so you can tell which layer produced which Proxy-Status entry.
Handle trailers intentionally
With streaming or large responses, conditions can change after headers are sent. RFC 9209 allows sending Proxy-Status as a trailer in those situations. Verify whether your clients and logging pipeline can collect and store trailer fields if you depend on that visibility.
FAQ
Should clients add it to requests?
No. Proxy-Status is a response header. It’s not intended for clients to add to requests to create meaning. If you need the normative definition, refer to the RFC.
Can you see it in a browser?
Often yes—developer tools (for example, the Network tab) may show it as a response header. However, visibility can vary by environment (browser behavior, extensions, corporate proxies, and CORS/exposed-header settings).
Is it useful for web scraping?
It won’t directly “bypass blocks,” but it’s very useful when your scraper runs through proxies. It helps you determine whether failures came from the proxy layer or the target site. For example, even if you see the same 429/403 on the surface, a proxy-reported error can push you toward investigating proxy configuration, routing, DNS, or upstream connectivity rather than assuming the site blocked you.
Summary
Proxy-Status is an HTTP response header that lets intermediaries like proxies and CDNs report their own handling outcomes to clients. It’s a practical way to distinguish proxy-layer issues (DNS, connection failures, timeouts, mid-stream termination) that don’t show up clearly in HTTP status codes alone. If you implement it, be deliberate about information exposure, multi-layer behavior, and whether you need to collect trailer fields. Start by capturing Proxy-Status with curl and in application logs—then use it as a high-signal clue during incident response.
References
