Cache HTTP Error Responses

๐Ÿšง

400 error responses

As of Q2 2023, 400 error responses are no longer cached from origin. See Caching 400 responses

Cache error responses from the origin to reduce traffic when content isnโ€™t available. With this behavior enabled, you can reduce the network traffic to your origin by caching HTTP error responses on the edge.

How it works

This behavior caches HTTP responses with these status codes on the edge servers:

  • 204 No Content
  • 305 Use Proxy
  • 404 Not Found
  • 405 Method Not Allowed
  • 500 Internal Server Error
  • 501 Not Implemented
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

When end-users request unavailable content, or the origin server responds with an error or specific non-error responses, the edge servers cache the response and serve it subsequent requests for the same content. By default, error responses with HTTP codes 204, 305, 404, 405, and 501 are cached for 10 seconds, and this feature allows you to modify the caching time. Error responses with HTTP codes 500, 502, 503, and 504 are not cached unless you disable the Preserve Stale Objects option.

๐Ÿšง

The default size limit for negative caching is 64 KB. The most common reason why the 404 error isn't cached is when the response size exceeds 64 KB. If you want to cache 404 error responses larger than 64KB, contact your Akamai account representative to have the limit increased.

Features and options

FieldWhat it does
EnableEnables or disables this behavior.
Max-ageSet the maximum time that cached objects can remain in the cache. A setting of 0 means no-cache, which forces revalidation before serving the content. Be aware that no-cache can cause a large increase in traffic to the origin in circumstances where that would be counterproductive (for example, when the origin is returning 500 errors).
Preserve Stale ObjectsBy default, edge servers keep and serve stale cached objects when receiving status codes 500, 502, 503, and 504 from the origin server, so that end-user clients can access content during transient errors without re-fetching and re-caching content from the origin. Disable this option to evict the stale object in cache and negatively cache the error instead.

Avoid cache poisoning attacks

A cache poisoning attack happens when false information is included in a cache, such as โ€‹Akamaiโ€‹'s cache. A query to that cache returns an incorrect response, for example an incorrect page or default error page.

A cache poisoning attack can occur if a request contains a request header with an invalid character. โ€‹Akamaiโ€‹ may pass this request header to the origin server and cache the error response on the edge servers, assuming the response is valid.

To avoid this problem:

  • You can use โ€‹Akamaiโ€‹'s Kona Site Defender. This offers WAF rules that would automatically detect an invalid character. Talk to your account representative to get Kona Site Defender added to your contract.
  • You can use a custom WAF. Set up a custom WAF on your site or app to recognize invalid characters in a request header.

Caching 400 responses

If you need โ€‹Akamaiโ€‹ to cache 400 responses from the origin, you can define a variable in your Property Manager configuration called PMUSER_AK_INT_CACHE_400 with a value of true (in lowercase).

You do not need to reference this variable anywhere else in your Property Manager configuration. โ€‹Akamaiโ€‹โ€™s internal code checks for the existence and value of this variable and ensures that 400 responses are cached using the TTL specified in the Cache HTTP Error Responses behavior.

๐Ÿšง

If this variable is not defined in your Property Manager configuration or if it is defined with any value other than true, 400 responses from your origin will not be cached.