X-Proxy-Cache
The HTTP X-Proxy-Cache response header is an unofficial HTTP header added by reverse proxies to indicate the cache status of a response.
Note
The "X-" naming convention for HTTP headers, "X" referring to "experimental", has been deprecated and needs to be transitioned to the formal naming convention for HTTP headers.
Usage
Reverse proxies like Nginx, Varnish, and other
Caching layers add the X-Proxy-Cache header to
responses to report whether the content was served
from cache or fetched from the origin server. The
header name varies by configuration. Nginx exposes the
$upstream_cache_status variable, and administrators
commonly map this variable to X-Proxy-Cache or
X-Cache-Status using the add_header directive.
The header carries a single keyword value describing
what happened when the proxy checked its cache. This
makes cache debugging straightforward. A HIT
confirms the proxy served stored content. A MISS
means the proxy forwarded the request to the origin.
Other values like BYPASS, EXPIRED, and STALE
describe specific caching scenarios.
Unlike X-Cache, which is associated with CDN providers like AWS CloudFront and Fastly, X-Proxy-Cache is more common on self-hosted infrastructure running Nginx or similar proxy software.
Values
HIT
The HIT value means the response was served directly
from the proxy cache. The cached content was fresh and
valid, so the origin server was not contacted.
MISS
The MISS value means the proxy had no cached copy
of the requested resource. The response was fetched
from the origin server and is typically stored in the
cache for subsequent requests.
BYPASS
The BYPASS value means the proxy intentionally
skipped the cache and fetched the response from the
origin server. This happens when a request matches a
proxy_cache_bypass rule in the proxy configuration,
often triggered by specific Cookies, query
parameters,
or Cache-Control directives.
EXPIRED
The EXPIRED value means a cached copy existed but
its freshness lifetime had passed. The proxy fetched
a new response from the origin server. The updated
content replaces the stale entry in the cache.
STALE
The STALE value means the proxy served an outdated
cached copy because the origin server was not
responding correctly. This behavior requires the
proxy_cache_use_stale directive to be configured,
allowing the proxy to fall back to stale content
during origin failures.
UPDATING
The UPDATING value means the cached content is
stale and currently being refreshed in the background.
The proxy served the old copy to avoid making the
client wait for the origin response. This requires
both proxy_cache_use_stale updating and
proxy_cache_background_update to be enabled.
REVALIDATED
The REVALIDATED value means the proxy sent a
conditional request to the origin server using
If-Modified-Since or If-None-Match headers. The
origin confirmed the cached content was still current,
and the proxy served the existing cached copy.
Example
A HIT means the proxy already had a fresh copy of
the resource stored in its cache. The response was
served without contacting the origin server.
X-Proxy-Cache: HIT
A MISS means the proxy had no cached copy. The
response was fetched from the origin server and stored
for future requests.
X-Proxy-Cache: MISS
An EXPIRED response indicates the cached entry had
passed its freshness lifetime. The proxy fetched new
content from the origin to replace the stale entry.
X-Proxy-Cache: EXPIRED
Takeaway
The X-Proxy-Cache header reports the cache status of a response from a reverse proxy. The single keyword value makes cache behavior immediately visible in response headers, simplifying debugging for operators running Nginx, Varnish, or similar proxy software.