Freshness and caching
Stale-if-error for page reads: serve the old copy or fail?
Use RFC 5861's stale-if-error as a model for your own page store: when a live read fails, decide how old a fallback copy may be and label it.
By Curtis Mccann, Live Web Data team · Published
This article was drafted with AI assistance from the sources listed below and edited and published by the Live Web Data team. Disclosure: the Live Web Data API, which this article mentions, is this site's own product.
- 1Try the live read firstA successful read is used and stored with its fetch time.
- 2Check the kind of failureRFC 5861 counts a 500, 502, 503 or 504 as an error. A 404 is an answer, not an outage.
- 3Check the copy's ageServe the stored copy only while its age is inside your fallback window, for example 1800 seconds.
- 4Label the copyTell the model and the user the fetch time of the copy and that the live read failed.
- 5Otherwise failPast the window, pass the error on instead of an old page.
Your app reads a page live, and the read fails. The site returns a 503, or the request times out. You have a copy of the same page from earlier in your own store. Do you put that copy in front of the model, or do you tell the user the page could not be read? HTTP caches answered this question years ago, and their answer works as a model for your own store.
The model: stale-if-error from RFC 5861
RFC 5861, published in May 2010 by Mark Nottingham as an informational document, defines two Cache-Control extensions for stale content. Both take a number of seconds.
stale-while-revalidatelets a cache serve a stale response for a limited number of seconds while it checks for a new one in the background.stale-if-errorlets a cache use a stale stored response when an error occurs, regardless of other freshness information, for a limited number of seconds.
The RFC is specific about what counts as an error: any situation that would end in a 500, 502, 503 or 504 status code. It is just as specific about the end of the window. Once the stored response is staler than the stated value, it should not be used, and the error goes through to the client.
The RFC's own example is Cache-Control: max-age=600, stale-if-error=1200. The response is fresh for 600 seconds. If the cache tries to validate it at 900 seconds and gets a 500, it can return the stored 200 response with Age: 900. The stale window adds 1,200 seconds to the 600, so after 1,800 seconds (30 minutes) the cache returns the error. MDN's example uses larger numbers: max-age=604800, stale-if-error=86400 is fresh for 7 days and usable on error for 1 more day.
Decide what counts as an error
The fallback is for an outage, not for an answer you do not like. Start from the RFC's list and map your fetcher's failures onto it.
- A 500, 502, 503 or 504 from the site: an error. The fallback applies.
- A timeout or a connection that never completes: treat it like a 504. The site did not answer in time.
- A 404 or 410: the site answered. The page is not there. Serving last week's copy would hide a real change, so pass the result on.
- A 200 with content: the live read worked. Use it and store it with its fetch time.
The last case matters for the store. A fallback copy is only as good as the fetch time saved with it, so every successful read should write both.
Pick one window, in seconds
RFC 5861 counts the stale window from the end of the freshness lifetime. In your own store it is simpler to keep one number: the oldest a copy may be, measured from its fetch time, when you serve it after a failed read. In the RFC's example that total is 1,800 seconds.
The right value depends on what the page is used for. A status page copy from 30 minutes ago can be wrong in the one way that matters. A reference page copy from 1 day ago is often still correct. Choose the window per use, write it in seconds, and fail once a copy is older.
The decision fits in a few lines of Python with no dependencies:
from datetime import datetime, timedelta, timezone
FALLBACK_WINDOW = timedelta(seconds=1800)
ERRORS = {500, 502, 503, 504, "timeout"}
def decide(live_result, stored_fetched_at, now):
"""Return 'live', 'stale-copy' or 'fail'."""
if live_result == 200:
return "live"
if live_result not in ERRORS or stored_fetched_at is None:
return "fail"
if now - stored_fetched_at <= FALLBACK_WINDOW:
return "stale-copy"
return "fail"
now = datetime(2026, 11, 15, 9, 0, tzinfo=timezone.utc)
print(decide(503, now - timedelta(seconds=900), now)) # stale-copy
print(decide("timeout", now - timedelta(seconds=1900), now)) # fail
print(decide(404, now - timedelta(seconds=60), now)) # fail
The first copy is 900 seconds old and inside the window. The second is 1,900 seconds old and outside it. The third is only 60 seconds old, but a 404 is not on the error list.
Make the stale copy visible
RFC 5861 says a stale response that is used should still be visibly stale when sent, with a non-zero Age header and a warning header. RFC 9111, the June 2022 HTTP caching standard, later obsoleted the Warning header because it was not widely generated or surfaced to users. So the protocol no longer carries that signal for you. Your app has to.
Put two facts next to the content you pass to the model: the copy's fetch time in UTC, and that the live read failed. A line such as Copy fetched 2026-11-15 08:45 UTC. Live read at 09:00 UTC failed with 503. lets the model qualify its answer, and lets the user see why. Our post on fetch timestamps in context shows where that line goes in the prompt. The guide on live vs cached web data covers when a stored copy is good enough in the first place.
Where the store sits with a live API
On Live Web Data API, "Every request fetches the page live; there is no cache." The fallback store is therefore yours, and the response gives you what it needs: statuses[].fetchedAt is the fetch time to save with each copy. Trying the live read first does not add to the bill when it fails: "Failed fetches cost 0 credits." The API docs list the response fields.
Frequently asked questions
What does stale-if-error mean?
It is a Cache-Control extension from RFC 5861. It lets a cache use a stale stored response when an error occurs, for a set number of seconds past the response's freshness lifetime. RFC 5861 counts a 500, 502, 503 or 504 status code as an error.
How is stale-if-error different from stale-while-revalidate?
stale-while-revalidate lets a cache serve a stale response for a limited number of seconds while it checks for a new one in the background. stale-if-error only applies when fetching or validating a new copy fails.
Should a fallback copy be served when the page returns 404?
Usually not. RFC 5861 limits errors to the 500, 502, 503 and 504 status codes. A 404 means the site answered and the page is not there, so an old copy would hide a real change.
How do I mark a stale copy now that the Warning header is obsolete?
RFC 9111 obsoletes the Warning header because it was not widely generated or shown to users. Mark the copy in your own app instead: pass its fetch time and a note that the live read failed along with the content.
Sources
- RFC 5861: HTTP Cache-Control Extensions for Stale Content (Documentation)
- MDN: Cache-Control (Documentation)
- RFC 9111: HTTP Caching (Documentation)