The Cache-Status HTTP Response Header Field
Extracted elements (21)
List ordering in Cache-Status places the cache closest to the origin first and the cache closest to the user last, mirroring the request path so that the chain of cache handling can be reconstructed in order.
The `detail` parameter is intentionally limited in scope. Developers or operators needing to convey additional information interoperably are encouraged to register extension parameters or define another header field rather than overloading `detail`.
The `fwd` values are ordered from most specific to least specific so that implementations are guided to report the most precise reason for forwarding, improving debuggability. The value `miss` exists as a fallback when an implementation cannot distinguish between uri-miss and vary-miss.
The semantics of the `detail` parameter are always specific to the cache that sent it; even if a detail value from another cache shares the same string, it might not mean the same thing. Implementors must not assume cross-cache portability for detail values.
An intermediary SHOULD NOT append a Cache-Status member to responses that it generates locally, even if that intermediary contains a cache, unless the generated response is based upon a stored response (e.g., 304 or 206).
Each Cache-Status list member identifier MUST be a String or Token. Depending on deployment, this might be a product name, hostname, IP address, or generated string.
The most specific `fwd` reason known to the cache SHOULD be used, to the extent it is possible to implement.
When adding a value to the Cache-Status header field, caches SHOULD preserve the existing field value to allow debugging of the entire chain of caches handling the request.
The Cache-Status HTTP response header field is a Structured Fields List where each member represents a cache that handled the request. The first member represents the cache closest to the origin server; the last represents the cache closest to the user.
The `collapsed` parameter is a Boolean indicating whether the request was collapsed with one or more other forward requests. If true, the response was successfully reused; if false, a new request had to be made. If absent, the request was not collapsed. Only meaningful when `fwd` is present.
The `detail` parameter is a String or Token allowing caches to convey additional implementation-specific information not captured in other parameters. Its semantics are always specific to the cache that sent it; the same value from different caches may not have the same meaning.
The `fwd` parameter is a Token indicating why the request went forward toward the origin. Defined values from most to least specific are: bypass, method, uri-miss, vary-miss, miss, request, stale, partial.
The `fwd-status` parameter is an Integer indicating which HTTP status code the next-hop server returned for the forwarded request. It is only meaningful when `fwd` is present; if absent but `fwd` is present, it defaults to the status code sent in the response.
The `hit` parameter is a Boolean that, when true, indicates the request was satisfied from cache without being forwarded. A stale response used without going forward (e.g., because the origin is unavailable) can be considered a hit. `hit` and `fwd` are mutually exclusive.
The `key` parameter is a String conveying a representation of the cache key used for the response. The value may be implementation-specific.
The `stored` parameter is a Boolean indicating whether the cache stored the response; a true value indicates it did. This parameter is only meaningful when `fwd` is present.
The `ttl` parameter is an Integer indicating the response's remaining freshness lifetime in seconds as calculated by the cache, measured as closely as possible to when the response header section is sent. It may be negative to indicate staleness.
IANA has added 'Cache-Status' as a permanent entry in the 'Hypertext Transfer Protocol (HTTP) Field Name Registry' defined in RFC 9110 Section 18.4.
IANA has created the 'HTTP Cache-Status' registry at https://www.iana.org/assignments/http-cache-status, populated with the parameters defined in Section 2. New parameters are approved by designated expert per RFC 8126 Section 4.5.
Attackers can use information in Cache-Status to probe cache behavior and infer user activity. For example, knowing whether a cache has stored a response can enable timing attacks on sensitive data.
Exposing the cache key via the `key` parameter can help attackers understand cache key modifications, potentially assisting cache poisoning attacks. Merely obfuscating the key does not mitigate this risk; the header field can be omitted or restricted to authorized clients.