Skip to content

Grace responses

Grace responses ensure that intensely trafficked resources on a site continue to be served in a timely fashion.

The grace period for a given cache object (i.e. the cached response for a particular request) is the max-age for that object, plus 1 minute. For example, for a max-age of 5 minutes the grace period will be 6 minutes. However, if the response code is >= 500, then the grace period is 15 seconds.

If a request is received for a cache object within the grace period but outside of the max-age of the cache, the page cache can serve a “graced” object (i.e. the previously cached response for this request) immediately, and request a freshened resource from the origin servers. Once the cache is refreshed, subsequent requests are served the fresh response until the max age is reached and the cycle starts again.

An example timeline of requests for a particular URL:

  1. request at 00:00, no cache, request is served from the origin servers and cached for subsequent resources with a max-age of 5 minutes.
  2. request at 00:04, the cache is valid so the response is served from cache.
  3. request at 00:05, the cache has reached max-age but is within the grace period. The response is served with a “grace” copy of the current cache, while in the background the cached copy is refreshed from the origin servers.
  4. …etc.

Graced responses can be identified by the X-Cache: grace HTTP response header.

One practical implication of the grace period is that a site may serve cached objects which are up to 1 minute over the max-age of the cache.

Last updated: August 03, 2023

Relevant to

  • Node.js
  • WordPress