Grace Responses

Grace responses ensure that intensely trafficked resources on your 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 one minute, e.g. for a max-age of five minutes the grace period will be six 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.

Here’s 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.

You can identify a graced response by the X-Cache: grace HTTP response header.

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