Skip to content
Cloudflare Docs

Cache

Background

The Cache API ↗ allows fine grained control of reading and writing from the Cloudflare global network ↗ cache.

The Cache API is available globally but the contents of the cache do not replicate outside of the originating data center. A GET /users response can be cached in the originating data center, but will not exist in another data center unless it has been explicitly created.

Workers deployed to custom domains have access to functional cache operations. So do Pages functions, whether attached to custom domains or *.pages.dev domains.

However, any Cache API operations in the Cloudflare Workers dashboard editor, Playground previews, and any *.workers.dev deployments will have no impact. For Workers fronted by Cloudflare Access ↗, the Cache API is not currently available.

Accessing Cache

The caches.default API is strongly influenced by the web browsers’ Cache API, but there are some important differences. For instance, Cloudflare Workers runtime exposes a single global cache object.

let cache = caches.default;
await cache.match(request);

You may create and manage additional Cache instances via the caches.open ↗ method.

let myCache = await caches.open('custom:cache');
await myCache.match(request);

Headers

Our implementation of the Cache API respects the following HTTP headers on the response passed to put():

  • Cache-Control
  • Cache-Tag
    • Allows resource purging by tag(s) later (Enterprise only).
  • ETag
    • Allows cache.match() to evaluate conditional requests with If-None-Match.
  • Expires string
    • A string that specifies when the resource becomes invalid.
  • Last-Modified
    • Allows cache.match() to evaluate conditional requests with If-Modified-Since.

This differs from the web browser Cache API as they do not honor any headers on the request or response.

Methods

Put

cache.put(request, response);

  • put(request, response) : Promise

    • Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to undefined regardless of whether the cache successfully stored the response.

Parameters

  • request string | Request

    • Either a string or a Request object to serve as the key. If a string is passed, it is interpreted as the URL for a new Request object.

  • response Response

    • A Response object to store under the given key.

Invalid parameters

cache.put will throw an error if:

  • The request passed is a method other than GET.
  • The response passed has a status of 206 Partial Content ↗.
  • The response passed contains the header Vary: *. The value of the Vary header is an asterisk (*). Refer to the Cache API specification ↗ for more information.

Errors

cache.put returns a 413 error if Cache-Control instructs not to cache or if the response is too large.

Match

cache.match(request, options);

  • match(request, options) : Promise<Response | undefined>

    • Returns a promise wrapping the response object keyed to that request.

Parameters

  • request string | Request

    • The string or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.

  • options

    • Can contain one possible property: ignoreMethod (Boolean). When true, the request is considered to be a GET request regardless of its actual value.

Unlike the browser Cache API, Cloudflare Workers do not support the ignoreSearch or ignoreVary options on match(). You can accomplish this behavior by removing query strings or HTTP headers at put() time.

Our implementation of the Cache API respects the following HTTP headers on the request passed to match():

  • Range

    • Results in a 206 response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if an Accept-Ranges header is on the response.

  • If-Modified-Since

    • Results in a 304 response if a matching response is found with a Last-Modified header with a value after the time specified in If-Modified-Since.

  • If-None-Match

    • Results in a 304 response if a matching response is found with an ETag header with a value that matches a value in If-None-Match.

  • cache.match()

    • Never sends a subrequest to the origin. If no matching response is found in cache, the promise that cache.match() returns is fulfilled with undefined.

Errors

cache.match generates a 504 error response when the requested content is missing or expired. The Cache API does not expose this 504 directly to the Worker script, instead returning undefined. Nevertheless, the underlying 504 is still visible in Cloudflare Logs.

If you use Cloudflare Logs, you may see these 504 responses with the RequestSource of edgeWorkerCacheAPI. Again, these are expected if the cached asset was missing or expired. Note that edgeWorkerCacheAPI requests are already filtered out in other views, such as Cache Analytics. To filter out these requests or to filter requests by end users of your website only, refer to Filter end users.

Delete

cache.delete(request, options);
  • delete(request, options) : Promise<boolean>

Deletes the Response object from the cache and returns a Promise for a Boolean response:

  • true: The response was cached but is now deleted
  • false: The response was not in the cache at the time of deletion.

Parameters

  • request string | Request

    • The string or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.

  • options object

    • Can contain one possible property: ignoreMethod (Boolean). Consider the request method a GET regardless of its actual value.