Cache API overview and global availability
The Cache API allows fine-grained control of reading and writing from the Cloudflare global network cache. It is a programmatic interface for reading from and writing to Cloudflare's cache from inside a Worker. The Cache API is available globally, but cache contents do not replicate outside of the originating data center. Workers deployed to custom domains have access to functional cache operations, as do Pages functions whether attached to custom domains or *.pages.dev domains. Cache API operations in the Cloudflare Workers dashboard editor and Playground previews will have no impact. For Workers fronted by Cloudflare Access, the Cache API is not currently available.
Cache API differs from Workers Caching mechanism
The Cache API is a programmatic interface for reading from and writing to Cloudflare's cache from inside a Worker. To cache responses from your Worker so that Cloudflare returns them without executing your Worker, use Workers Caching instead. The two mechanisms are independent.
cache.put method not compatible with tiered caching
The cache.put method is not compatible with tiered caching. To perform tiered caching, use the fetch API instead of cache.put.
Accessing default cache object
Access the default cache object using caches.default. The Cloudflare Workers runtime exposes a single global cache object. Example: let cache = caches.default; await cache.match(request);
Creating and managing additional Cache instances
Additional Cache instances can be created and managed via the caches.open method. Example: let myCache = await caches.open('custom:cache'); await myCache.match(request);
Cache API headers respected by put method
The Cache API implementation respects the following HTTP headers on the response passed to put(): Cache-Control (controls caching directives, consistent with Cloudflare Cache-Control Directives), Cache-Tag (allows resource purging by tag(s) later), ETag (allows cache.match() to evaluate conditional requests with If-None-Match), Expires (a string that specifies when the resource becomes invalid), and Last-Modified (allows cache.match() to evaluate conditional requests with If-Modified-Since).
Set-Cookie header responses never cached
Responses with Set-Cookie headers are never cached because this sometimes indicates that the response contains unique data. To store a response with a Set-Cookie header, either delete that header or set Cache-Control: private=Set-Cookie on the response before calling cache.put().
cache.put method signature and behavior
cache.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.
cache.put parameters
cache.put takes two 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) and response (Response, a Response object to store under the given key).
cache.put invalid parameter conditions
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; or the response passed contains the header Vary: * (the value of the Vary header is an asterisk).
cache.put error conditions
cache.put returns a 413 error if Cache-Control instructs not to cache or if the response is too large.
cache.put redirect response cache-poisoning mitigation
cache.put will silently reject a 301 or 302 redirect response if both of the following are true: (1) the cache key does not include the query string (for example, a custom cache key set via Workers or Page Rules that strips the query string), and (2) the Location header in the redirect response contains the request's query string. This is a cache-poisoning mitigation. To cache redirect responses with query strings, either include the query string in your cache key or remove the query string from the Location header before calling cache.put(). This restriction does not apply on .workers.dev domains, which include the query string in the cache key by default.
stale-while-revalidate and stale-if-error not supported with cache methods
The stale-while-revalidate and stale-if-error directives are not supported when using the cache.put or cache.match methods.
cache.match method signature and behavior
cache.match(request, options) : Promise<Response | undefined>. Returns a promise wrapping the response object keyed to that request.
cache.match parameters
cache.match takes two 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) and options (object, can contain one possible property: ignoreMethod (Boolean), when true, the request is considered to be a GET request regardless of its actual value).
cache.match unsupported browser options
Cloudflare Workers do not support the ignoreSearch or ignoreVary options on cache.match(), unlike the browser Cache API. You can accomplish this behavior by removing query strings or HTTP headers at put() time.
cache.match request headers respected
The Cache API implementation respects the following HTTP headers on the request passed to cache.match(): Range (results in a 206 response if a matching response with a Content-Length header is found; 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 before the time specified in If-Modified-Since), and 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 subrequest to origin
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.
cache.match 504 error handling
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. These 504 responses have the RequestSource of edgeWorkerCacheAPI.
cache.delete method signature and return value
cache.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) or false (the response was not in the cache at the time of deletion).
cache.delete parameters
cache.delete takes two 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) and options (object, can contain one possible property: ignoreMethod (Boolean), consider the request method a GET regardless of its actual value).
cache.delete only purges local data center
The cache.delete method only purges content of the cache in the data center that the Worker was invoked. For global purges, refer to purging assets stored with the Cache API documentation.