Summary

  • Cache-Control: only-if-cached asks for a stored response only; an honoring cache should return a suitable stored response or 504.
  • That 504 can be generated without contacting the origin, so it proves failure of the cache-only retrieval rather than origin unavailability.

Consider an explicitly hypothetical availability probe. Its operator wants to test whether a configuration snapshot is resident at an edge, so the probe sends a GET with Cache-Control: only-if-cached. The edge has no stored response that satisfies the request and returns 504. An alerting rule sees only the status code, labels it an origin timeout and pages the origin team. Yet the cache did exactly what the probe requested: it did not forward, and the origin received no request.

The ambiguity arises because 504 has a general meaning and a cache-specific use. RFC 9110 defines Gateway Timeout as a gateway or proxy not receiving a timely response from an upstream server it needed to access. RFC 9111 then gives a cache honoring only-if-cached two outcomes: return a stored response consistent with the request’s other constraints, or return 504. In that branch, the client requested that no upstream retrieval occur.

The directive therefore changes the experiment. It does not ask, “Can the origin answer?” It asks, “Can this cache satisfy the request from a stored response it is allowed to reuse?” Treating the result as a normal end-to-end availability probe collapses two different control paths.

A stored response’s mere presence is not enough. RFC 9111 still requires the target and method to match, nominated Vary fields to match, validation requirements to be satisfied, and the response to be fresh, successfully validated or permitted to be served stale. A cache can possess bytes for the URI and still have no eligible answer. The 504 can therefore mean “nothing suitable here under these constraints,” not even “nothing stored here.”

Nor does the status disclose which cache made the decision. A request can cross a browser cache, enterprise proxy, CDN and gateway. Operators need the responding cache identity, the directive observed at that hop, the candidate lookup result and whether forwarding was suppressed. Without those facts, a status-only dashboard assigns responsibility by convention rather than evidence.

This distinction matters operationally. Origin incidents and cache-residency failures have different owners, rollback actions and customer implications. Paging the origin team for a deliberately local miss wastes the first minutes of an incident. Worse, a successful ordinary probe run beside the cache-only probe might be misread as intermittent origin behavior rather than evidence that the two probes asked different questions.

Use a cache-only decision receipt. This is an editorial control construct, not an IETF-defined protocol object. Bind the request target and method, all Cache-Control request directives, cache identity and lookup key, candidate responses, Vary comparison, freshness or stale authority, validation requirement, selected response or miss, forwarding decision and any upstream-attempt trace. Then classify the result as cache eligibility, forwarding policy or upstream timing.

The receipt makes negative evidence useful. “No upstream attempt” does not prove the origin was healthy; it proves this observation cannot establish that the origin failed. A separate probe without the cache-only constraint is required for origin reachability. One status code can remain standards-conformant while supporting different causal stories. The request and execution trace decide which story is justified.

Sources