# Cache settings A cache setting is an object on an application that tells [Cache](/en/documentation/platform/applications/#cache) how to store and serve a response. It holds the browser TTL, the cache TTL and behavior, stale cache, Large File Optimization, [Tiered Cache](/en/documentation/platform/applications/cache/tiered-cache/), and the cache variation rules. A [Rules Engine](/en/documentation/platform/applications/rules-engine/) rule with the [Set Cache Policy](/en/documentation/platform/applications/rules-engine/#set-cache-policy) behavior applies the setting to the requests it matches. Until a rule names it, a setting does nothing. To create one, refer to [Create a cache setting](/en/documentation/guides/application-performance/cache-and-purge/tune-cache-settings/). --- ## Interfaces Six interfaces write the same object. The tables on this page name the Console control, the API field, and the CLI flag of each field. | Interface | Create | Read, update, delete | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Azion Console](https://console.azion.com/) | The **Cache Settings** tab of an application in [Applications](/en/documentation/platform/applications/), then **+ Cache**, which opens the **Create Cache Settings** drawer | The same tab lists every setting with its **Name**, **ID**, **Browser Cache**, and **Cache** | | [Azion API v4](/en/documentation/devtools/api/) | `POST /v4/workspace/applications/{application_id}/cache_settings` | `GET`, `PATCH`, and `DELETE /v4/workspace/applications/{application_id}/cache_settings/{cache_setting_id}`; `GET /v4/workspace/applications/{application_id}/cache_settings` lists them | | Azion CLI | [`azion create cache-setting`](/en/documentation/devtools/cli/resources/) | [`azion describe cache-setting`](/en/documentation/devtools/cli/resources/), [`azion list cache-setting`](/en/documentation/devtools/cli/resources/), [`azion update cache-setting`](/en/documentation/devtools/cli/resources/), [`azion delete cache-setting`](/en/documentation/devtools/cli/resources/) | | `azion.config.js` | An entry of the `cache` array, of type `AzionCache` | The same entry | | [Azion Lib](/en/documentation/devtools/azion-lib/application/) | `createCacheSetting` from `azion/applications` | `getCacheSetting`, `getCacheSettings`, `updateCacheSetting`, and `deleteCacheSetting` from `azion/applications` | | [Terraform](/en/documentation/devtools/terraform/applications/) | The `azion_application_cache_setting` resource, whose page documents `application_id` and `name` | The same resource | The API authenticates with a personal token in the `Authorization: Token ` header. For more information, refer to [Personal tokens](/en/documentation/guides/platform/account-and-billing/personal-tokens/). An `AzionCache` entry carries `name`, `stale`, `queryStringSort`, `tieredCache`, `methods`, `browser.maxAgeSeconds`, `edge.maxAgeSeconds`, `cacheByCookie`, and `cacheByQueryString`. --- ## General The **General** section of the drawer holds the name. The API requires `name` and nothing else. | Console control | API field | Type | Values | Default | CLI flag | | --------------- | --------- | ------ | ------------------- | -------------------- | -------- | | **Name** | `name` | string | 1 to 250 characters | required, no default | `--name` | --- ## Browser Cache The **Browser Cache** section decides what the browser is told to keep, through the `browser_cache` object. | Console control | API field | Type | Values | Default | CLI flag | | --------------------------------------------- | ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------- | ------- | -------------------------- | | **Browser Cache** radios | `browser_cache.behavior` | enum | *Honor cache policies* (`honor`), *Override cache settings* (`override`), *No cache* (`no-cache`) | `honor` | `--browser-cache-behavior` | | The TTL field under *Override cache settings* | `browser_cache.max_age` | integer, seconds | 0 to 31,536,000 | `0` | `--browser-cache-max-age` | *Honor cache policies* keeps the `Cache-Control` and `Expires` headers the origin sends and forwards them to the browser. *Override cache settings* replaces them with the TTL in `browser_cache.max_age`. For *No cache*, the Console reads: "Disable browser caching to ensure content is always fetched directly from the server". On `azion update cache-setting`, the flag for `browser_cache.behavior` is `--browser-cache-settings`. --- ## Cache The **Cache** section sets how long Azion keeps the copy and what it does with it, through the `modules.cache` object. | Console control | API field | Type | Values | Default | CLI flag | | --------------------------- | ---------------------------------------- | ---------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | **Cache Behavior** radios | `modules.cache.behavior` | enum | *Honor cache policies* (`honor`), *Override cache behavior* (`override`) | `honor` (API, CLI); *Override cache behavior* preselected in the Console | `--file` only | | **Max Age** | `modules.cache.max_age` | integer, seconds | 0 to 31,536,000 | `60` (API, CLI, Console) | `--file` only | | **Stale cache** | `modules.cache.stale_cache.enabled` | boolean | `true`, `false` | `false` (API, CLI); on in the Console | `--file` only | | **Large file optimization** | `modules.cache.large_file_cache.enabled` | boolean | `true`, `false` | `false` (API, CLI); off in the Console | `--file` only | | **Offset (KB)** | `modules.cache.large_file_cache.offset` | integer, kB | `1024`, fixed | `1024` | `--file` only | | **Tiered Cache** | `modules.cache.tiered_cache.enabled` | boolean | `true`, `false` | `false` when no `tiered_cache` object is sent; `true` inside a `tiered_cache` object that omits it; off in the Console | `--tiered-caching-enabled` alone fails with error `21001`; use `--file` | | **Tiered Cache Region** | `modules.cache.tiered_cache.topology` | enum | `nearest-region`, `br-east-1`, `us-east-1` | none | `--file` only | *Honor cache policies* keeps the `Cache-Control` and `Expires` headers the origin sends; *Override cache behavior* replaces them with **Max Age**. **Stale cache** lets Azion serve an expired copy when the origin fails. **Large file optimization** stores a large object in fragments of 1,024 kB. **Tiered Cache** adds a second cache layer between Azion's cache and the origin. For how each one behaves on a request, refer to [Expiration and freshness](/en/documentation/platform/applications/cache/expiration-and-freshness/). > **Note** > > Two constraints bind these values. A **Max Age** below 60 seconds requires [Application Accelerator](/en/documentation/platform/applications/#application-accelerator) on the application; without it, the API rejects the setting with error `21021`. Tiered Cache requires *Override cache behavior*; with `honor`, the API rejects the setting with error `21001`. --- ## Application Accelerator The four **Cache vary by** controls of the **Application Accelerator** section write the `modules.application_accelerator` object. Every field in it requires the [Application Accelerator](/en/documentation/platform/applications/#application-accelerator) module on the application, or the API returns error `21013`. The query-string and cookie fields configure **Advanced Cache Key**; the device fields use the groups defined in [Device Groups](/en/documentation/platform/applications/device-groups/). For what each behavior does to the cache key, refer to [Application Accelerator settings](/en/documentation/platform/applications/application-accelerator/settings/). | Console control | API field | Type | Values | Default | CLI flag | | ----------------------------------------------------- | ---------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- | | **Cache vary by Method** > **POST**, **OPTIONS** | `cache_vary_by_method` | array of enum, at most 2 values | `post`, `options` | `[]` | `--enable-caching-for-options` for `options`; `--file` for `post` | | **Cache vary by Query String** > **Behavior** | `cache_vary_by_querystring.behavior` | enum | *Ignore* (`ignore`), *All* (`all`), *Allowlist* (`allowlist`), *Denylist* (`denylist`) | `ignore` | `--cache-by-query-string` | | The field list under **Cache vary by Query String** | `cache_vary_by_querystring.fields` | array of string | query string argument names | `[]` | `--query-string-fields` | | **Cache vary by Query String** > **Sort** | `cache_vary_by_querystring.sort_enabled` | boolean | `true`, `false` | `false` | `--file` only | | **Cache vary by Cookies** > **Behavior** | `cache_vary_by_cookies.behavior` | enum | *Ignore* (`ignore`), *All* (`all`), *Allowlist* (`allowlist`), *Denylist* (`denylist`) | `ignore` | `--cache-by-cookies` | | The cookie list under **Cache vary by Cookies** | `cache_vary_by_cookies.cookie_names` | array of string | cookie names | `[]` | `--cookie-names` | | **Cache vary by Devices** > **Behavior** | `cache_vary_by_devices.behavior` | enum | *Ignore* (`ignore`), *Allowlist* (`allowlist`) | `ignore` | `--file` only | | The device group list under **Cache vary by Devices** | `cache_vary_by_devices.device_group` | array of integer | device group ids | `[]` | `--file` only | *Ignore* varies the key by none of the values, and *All* by every value that arrives. *Allowlist* varies it by the named values, and *Denylist* by every value except the named ones. *Allowlist* and *Denylist* on the query string need at least one field, or the API returns error `21018`. For the Console steps that set these controls, refer to [Configure Advanced Cache Key for an application](/en/documentation/guides/application-performance/cache-and-purge/advanced-cache-key/). --- ## Request body The request body below creates a complete cache setting through `POST /v4/workspace/applications/{application_id}/cache_settings`: ```json { "name": "static-assets", "browser_cache": { "behavior": "override", "max_age": 86400 }, "modules": { "cache": { "behavior": "override", "max_age": 300, "stale_cache": { "enabled": true }, "large_file_cache": { "enabled": true, "offset": 1024 }, "tiered_cache": { "enabled": true, "topology": "nearest-region" } } } } ``` The API answers with HTTP `201`, `state` set to `executed`, and the new object with its `id` under `data`: ```json {"state":"executed","data":{"id":123456,"name":"static-assets",...,"created_at":"2026-01-01T12:00:00.577248Z"}} ``` The list endpoint wraps the settings of an application in a page envelope: ```json {"count":2,"total_pages":1,"page":1,"page_size":10,"next":null,"previous":null,"results":[...]} ``` The CLI writes the fields its flags cover from the command line: ```bash azion create cache-setting \ --application-id \ --name "product-listing" \ --browser-cache-behavior override \ --browser-cache-max-age 30 \ --cache-by-query-string allowlist \ --query-string-fields "category,page" \ --cache-by-cookies allowlist \ --cookie-names "session_id" ``` The command prints the id of the new setting: ```text Created Cache Settings configuration with ID 123457 ``` The flags cover browser cache, query-string and cookie variation, and OPTIONS caching. Every other field, including **Max Age**, the cache behavior, stale cache, Large File Optimization, and Tiered Cache, is set through `--file` with the JSON body. --- ## Errors The API answers each request below with HTTP `400`. The body carries the code and the title, and a field error also points at the field. | Code | Title | Cause | What to do | | ------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `21021` | `Edge Cache Max Age Lower Than The Minimum Allowed By Application's Application Accelerator Module` | `modules.cache.max_age` is below 60 on an application without Application Accelerator; `meta.min_value` is `60`, and the detail reads `The value is lower than the minimum required when the Application's Application Accelerator Module is disabled.` and points at `/data/modules/cache/max_age`. | Set **Max Age** to 60 or more, or turn on Application Accelerator on the application. | | `21020` | `Edge Cache Max Age Lower Than The Minimum Allowed By The Tiered Cache Module` | `modules.cache.max_age` is below 3 with `tiered_cache.enabled` set to `true`; `meta.min_value` is `3`, and the detail reads `The value is lower than the minimum required by the Tiered Cache Module.` and points at `/data/modules/cache/max_age`. | Set **Max Age** to 3 or more, or turn Tiered Cache off. | | `21001` | `It's Not Possible To Use This Edge Cache Behavior.` | `tiered_cache.enabled` is `true` while `modules.cache.behavior` is `honor`; the detail reads `It's not possible to use this edge cache behavior while using Tiered Cache.` and points at `/data/modules/cache/behavior`. `azion create cache-setting --tiered-caching-enabled true` sends this combination, because no flag sets the behavior. | Set `modules.cache.behavior` to `override`; from the CLI, send the body with `--file`. | | `21013` | `This Configuration Requires The Edge Application's Application Accelerator Module` | A `modules.application_accelerator` field is sent for an application without the module; the detail reads `To use this value, you must first enable the Application Accelerator module in Edge Application's Main Settings.` and points at the field, such as `/data/modules/application_accelerator/cache_vary_by_method`. | Turn on **Application Accelerator** under **Main Settings** > **Modules**, or remove the field. | | `21018` | `Query String Fields Are Required For Current Cache Vary By Query String Behavior` | `cache_vary_by_querystring.behavior` is `allowlist` or `denylist` and `fields` is empty; the detail reads `The current behavior requires you to configure query string fields.` and points at `/data/modules/application_accelerator/cache_vary_by_querystring/fields`. | List at least one field, or set the behavior to `ignore` or `all`. | | `21014` | `Cannot Delete Cache Setting` | A `DELETE` targets a setting that a rule's **Set Cache Policy** behavior still names; the detail reads `This Cache Setting cannot be deleted because it is being used.` and points at `/data`. | Change or delete that rule, then repeat the `DELETE`. | | `10068` | `Max Value` | `modules.cache.max_age` or `browser_cache.max_age` is above 31,536,000, with the detail `Ensure this value is less than or equal to 31536000.`; or `large_file_cache.offset` is above 1,024, with the detail `Ensure this value is less than or equal to 1024.` | Lower the value to the ceiling the detail names. | | `10046` | `Max Length` | `name` is longer than 250 characters; the detail reads `Ensure this field has no more than 250 characters.` | Shorten the name to 250 characters or fewer. | | `10039` | `Invalid Choice` | `tiered_cache.topology` is not `nearest-region`, `br-east-1`, or `us-east-1`. | Send one of the three values. | --- ## Limits The bounds below apply to one cache setting. Each row names the API's answer past the value. | Value | Bound | Past the bound | | ------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ | | `name` | 1 to 250 characters | HTTP `400`, error `10046` | | `modules.cache.max_age` | 0 to 31,536,000 seconds | HTTP `400`, error `10068` above the maximum | | `modules.cache.max_age` without Application Accelerator | at least 60 seconds | HTTP `400`, error `21021` | | `modules.cache.max_age` with Tiered Cache on | at least 3 seconds | HTTP `400`, error `21020` | | `browser_cache.max_age` | 0 to 31,536,000 seconds | HTTP `400`, error `10068` | | `cache_vary_by_method` | at most 2 values | The spec caps the array at 2 items; no error string is documented | | `large_file_cache.offset` | 1,024 kB, fixed | HTTP `400`, error `10068` above 1,024. To change the fragment size, contact the Sales team | For purge limits and the amounts each plan includes, refer to [Applications limits](/en/documentation/platform/applications/limits/#cache). --- ## Related resources - [Create a cache setting](/en/documentation/guides/application-performance/cache-and-purge/tune-cache-settings.md): The Console, API, and CLI steps that create a setting and apply it with a rule. - [Expiration and freshness](/en/documentation/platform/applications/cache/expiration-and-freshness.md): What the TTL, stale cache, Large File Optimization, and Tiered Cache do to a request. - [Cache keys](/en/documentation/platform/applications/cache/cache-keys.md): The key each variation in these tables appends to, and the debug headers that show it. - [Configure cache policies for an application](/en/documentation/guides/application-performance/cache-and-purge/cache-settings.md): The Console steps that set a TTL for a path and bypass the cache for another.