X-Cache-Status
The HTTP X-Cache-Status response header is an unofficial HTTP header indicating the cache state of a response as determined by a CDN or reverse proxy.
Usage
The X-Cache-Status header provides more detail than the binary HIT/MISS approach of X-Cache. Where X-Cache reports whether a response came from cache or the origin server, X-Cache-Status returns a specific state value describing what happened during the cache lookup. This makes debugging cache behavior more precise, especially in setups with multiple cache tiers.
Nginx's fastcgi_cache and proxy_cache modules
expose the $upstream_cache_status variable, but the
header itself is not added automatically. Operators
must add the header explicitly with
add_header X-Cache-Status $upstream_cache_status;
in their Nginx config. KeyCDN,
Varnish-based CDNs, and custom reverse proxy stacks
also use this header with compatible values. The
IETF has published the Cache-Status
header as the standardized replacement for
vendor-specific cache status headers.
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.
Values
HIT
The HIT value means the cache had a fresh copy
of the resource and served the response directly
without contacting the origin server.
MISS
The MISS value means no cached copy existed for
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 cache was intentionally
skipped for this request. This occurs when
Cache-Control directives mark the
response as uncacheable, when request parameters
trigger cache bypass rules, or when the server
configuration excludes certain paths from caching.
EXPIRED
The EXPIRED value means a cached copy existed but
had passed its freshness lifetime. The cache fetched
a new response from the origin server and updated
the stored entry.
STALE
The STALE value means the cache served an outdated
copy of the resource. This happens when the cache is
configured to serve stale content while revalidating
in the background, controlled by directives like
proxy_cache_use_stale in Nginx.
UPDATING
The UPDATING value means the cache is actively
refreshing a stale entry in the background. The
current request received the old cached response
while the updated version is being fetched from
the origin server. This is closely related to
STALE and depends on the
proxy_cache_use_stale updating directive in Nginx.
REVALIDATED
The REVALIDATED value means a stale cache entry
was validated against the origin server using
conditional requests. The
origin confirmed the cached version is still valid,
so the cache refreshed the entry's freshness
lifetime and served the stored copy.
Example
A HIT means the reverse proxy or CDN had a fresh
copy stored and served the response without
contacting the origin server.
X-Cache-Status: HIT
A MISS means no cached copy existed. The response
was fetched from the origin and stored for future
requests.
X-Cache-Status: MISS
A BYPASS means the cache was intentionally skipped
for this request, often due to cache control rules
or uncacheable content types.
X-Cache-Status: BYPASS
Some CDN configurations include a multi-tier format showing the status at each cache layer. In this example from a Turkish CDN, the edge cache and mid-tier cache both reported a miss.
X-Cache-Status: Edge : MISS, Midcache : MISS
Takeaway
The X-Cache-Status header reports the specific cache state of a response, providing more granular feedback than a simple HIT or MISS. The header is widely used in Nginx and CDN environments for debugging Caching behavior.