Skip to content
← cd ../posts
[Developer Tools]Updated 4 min read

HTTP Caching: Debug Stale Responses Without Guessing

Trace stale API responses through browser and CDN caches, read Cache-Control and ETag correctly, and verify changes with a repeatable checklist.

Quick answer

To debug a stale response, identify which layer served it before clearing caches. Freshness determines when a stored response can be reused; validation checks whether it is still current. Compare the response version, Cache-Control, ETag, Age, and Vary across the application, CDN, and browser.

Browser and edge caches hold amber document cards while a validation loop connects them to an updated teal document at the origin.

You update a product description, confirm the database write, and open the page. The old description is still there. A hard refresh fixes your tab, but a colleague still sees yesterday's content. Before changing database code or adding random query parameters, identify which layer supplied the response.

This walkthrough uses a public product-catalog endpoint. The goal is to turn “the cache is broken” into a reproducible observation: a particular URL, representation, cache policy, and response version.

Capture the Response Before Clearing Anything

Start with one affected URL and record the response body or a harmless version marker. Capture the request method, query string, response status, Cache-Control, ETag, Age, Date, and Vary headers when present. Also note whether your browser reports a memory-cache, disk-cache, or service-worker response.

Keep the browser's normal cache behavior enabled for this first capture. Clearing everything immediately removes the evidence that explains the failure. Compare the failing request with a working request under the same account, locale, and query parameters. The API debugging checklist provides a useful baseline for that comparison.

Write a short incident note: “At 10:05, /api/catalog returned version 17 in this browser; the expected version is 18.” That is a stronger starting point than “refresh sometimes works.”

Separate Freshness From Validation

A cache can reuse a response while it is fresh under its policy. A validator such as an ETag helps check whether a stored representation remains valid. Those are separate decisions.

For the catalog example, suppose the response contains Cache-Control: public, max-age=300 and ETag: "catalog-v17". A matching stored response with a current age of 120 seconds can still be fresh, even if an editor changed the underlying catalog moments ago. The five-minute freshness policy allowed that delay.

When validation occurs, a matching If-None-Match value can lead to a 304 response and reuse of the stored body. If the selected representation changed, the server should provide the new representation and an appropriate validator. The MDN HTTP caching guide explains this freshness-and-validation flow.

For our investigation, record whether version 18 exists at the serving layer, not just in the database. An application cache or a stale static export can still produce version 17 before any HTTP cache gets involved.

Run One Controlled Browser Probe

Use a same-origin test endpoint that you own and whose response contains a non-sensitive version field. This browser snippet requests revalidation through the browser's HTTP cache and prints a small set of diagnostics:

javascript
async function inspectCatalog() {
  const response = await fetch('/api/catalog', {
    cache: 'no-cache',
    headers: { Accept: 'application/json' },
  });
  if (!response.ok) {
    throw new Error(`Catalog request failed: ${response.status}`);
  }
  const catalog = await response.json();
  return {
    status: response.status,
    version: catalog.version,
    cacheControl: response.headers.get('cache-control'),
    etag: response.headers.get('etag'),
    age: response.headers.get('age'),
  };
}

The Request.cache reference distinguishes no-cache, which validates a matching HTTP-cache entry, from reload, which bypasses its lookup and can update it, and no-store, which bypasses lookup and does not store the downloaded response there. These options control the browser's HTTP-cache behavior; they are not a universal purge command for your application or CDN.

After a successful HTTP-cache revalidation, JavaScript can receive a usable response with the stored body; do not require this snippet to expose the network's 304 status. Compare the body version and inspect the network details together. If a service worker controls the page, inspect its request handler as a separate layer.

The snippet is a diagnostic probe, not a production caching policy. Avoid logging whole catalog objects if they might later contain private fields.

Check the Response Policy and Cache Key

Under RFC 9111, an unqualified response directive no-cache permits storage but requires successful validation before reuse. no-store prohibits storage of that response; private prevents shared-cache storage. A new no-store response does not act as a purge of all previously stored copies.

Vary adds named request-header values to the conditions for matching a stored response. If your endpoint selects a language using Accept-Language, inspect whether its responses consistently identify that variation. Check the actual CDN configuration too: platform-specific cache-key rules need their own verification.

For the catalog incident, compare the English and French requests separately. Do not call a correct French representation “stale” because it differs from an English origin response. Keep the URL, relevant request headers, and expected representation together in the evidence.

For account-specific content, review whether shared caching is appropriate before tuning freshness. A faster response is not useful if it belongs to a different user.

Follow the Version Through Each Layer

Trace the response from the application outward. In an authorized development or staging environment, compare the application's output with the CDN-facing response, then with the browser. Preserve the same request identity at each step. If an origin is private, use its supported diagnostic path instead of exposing it publicly.

For each comparison, ask one concrete question: where does version 18 first become version 17? If the application already returns 17, investigate its data cache or build inputs. If the CDN-facing response differs, inspect its policy, age, and invalidation behavior. If the browser alone differs, inspect its HTTP cache and any service-worker storage.

Use the HTTP status explorer to interpret unfamiliar responses. A status code by itself does not identify which layer supplied the bytes.

Verify the Fix Under Normal Conditions

  • Capture the old response before clearing caches, including the URL and harmless version marker.
  • Confirm the serving application has the intended content, including any static rebuild requirement.
  • Match account, locale, query parameters, and representation-selecting headers across comparisons.
  • Repeat the request with normal caching, then run the controlled revalidation probe.
  • Test both an unchanged representation and a changed one to check validator behavior.
  • Confirm the intended update delay with a clock-based test rather than repeated manual refreshes.
  • Check a second browser or test client after the fix, with its normal cache settings restored.

Finish the incident with the failed boundary and the chosen policy. “The CDN reused catalog version 17 within its five-minute freshness window; we changed the catalog policy and verified version 18 through every layer” gives the next engineer something to test. “Cleared cache” does not.

Choose the cache policy deliberately
DirectiveWhat it means
no-cacheStorage is permitted, but successful validation is required before reuse.
no-storeDo not store this response; this is not a purge of earlier stored responses.
privateA shared cache must not store the response.
max-age=300The response has a freshness lifetime of 300 seconds; account for its current age.

Sources and further reading

These references explain the standards and APIs discussed in this guide. Check the documentation for the versions and services in your environment.

Related Posts

Useful Tools For This Topic

explore_all →