Skip to content

Grace responses

Grace responses ensure that intensely trafficked resources on a site continue to be served in a timely fashion. The page cache will return grace responses under certain circumstances.

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 12 hours over the max-age of the cache.

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 an extra time:

  • 15 seconds for response codes 429 and 431, and 5xx
  •  1 minute for uncacheable requests, and response codes 302307404410.
  •  12 hours for everything else.

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. If the origin returns a 5xx response, then the cached object will continue to be returned until the grace period has ended.

An example timeline of requests for a particular URL:

  1. request at 00:00 (midnight), no cache, request is served from the origin servers and cached for subsequent resources with a max-age of 30 minutes.
  2. request at 00:29, the cache is valid so the response is served from cache.
  3. request at 01:00, 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.

Last updated: January 29, 2024

Relevant to

  • Node.js
  • WordPress