RFC 9211 / START HERE
HTTP Cache-Status, before the details
Cache-Status is the name of an HTTP response header field, not an acronym. It reports how caches handled a request.
A cache keeps reusable copies of responses. When a response comes back, participating caches can add their names and facts such as whether they served a copy, forwarded the request or stored the result.
The idea in one picture
Follow the response
Read each cache report
Distinguish hit from forwarding
A simplified picture of the idea; the chapters explain the actual mechanisms.
Why it exists
Different products once used unrelated debug fields. RFC 9211 gives cache diagnostics a common format and defined meanings while leaving reporting optional. It does not change the caching rules.
A familiar example
A picture loads through two caches. Cache-Status helps an operator see which cache supplied a copy and which had to forward. An older inner-cache report may have been stored and reused, so it need not describe the current request.
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.
- Read cache reports in response orderEach cache can append a report, ordered from the origin side toward the user.→
- Separate hits, freshness and next-hop statusFreshness, forwarding and storage are independent facts reported by different parameters.→
- Explain why a request went forwardDifferent failed selections and request rules lead to distinct fwd reason tokens.→
- Report collapsed requests and storageSeveral waiting requests can share one forward request, but reuse can also fail.→
- Expose useful diagnostics carefullyKeys and implementation details help debugging but can expose sensitive cache behavior.→
This introduction explains RFC 9211 (2022). Read the original RFC ↗