You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info
![](https://docs.apigee.com/static/api-platform/images/icon_policy_traffic-management.jpg)

Configures how the cached values should be purged from the cache.

This policy is intended for use in general purpose short-term caching. It is used in
conjunction with the [Populate
Cache policy](https://docs.apigee.com/api-platform/reference/policies/populate-cache-policy) (for writing entries) and the [Lookup Cache policy](https://docs.apigee.com/api-platform/reference/policies/lookup-cache-policy) (for reading cache entries).

For caching the responses of backend resources, see the
[Response Cache policy](https://docs.apigee.com/api-platform/reference/policies/response-cache-policy).

> [!NOTE]
> **Note:** If you want to clear a cache outside of a message flow, without policies, you can use the [Clear a cache entry](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/caches/{cache_name}/entries/{entry}) management API.

## Element reference

The following lists the elements you can configure on this policy.

```
<InvalidateCache async="false" continueOnError="false" enabled="true" name="policy-name">
    <DisplayName>Policy Name</DisplayName>
    <CacheKey>
        <Prefix>prefix_string</Prefix>
        <KeyFragment ref="variable_reference"/>
        <KeyFragment>fragment_string</KeyFragment>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource>cache_to_use</CacheResource>
    <Scope>scope_enumeration</Scope>
    <CacheContext>
        <APIProxyName>application_that_added_the_entry</APIProxyName>
        <ProxyName>proxy_for_which_data_was_cached</ProxyName>
        <TargetName>endpoint_for_which_data_was_cached</TargetName>
    </CacheContext>
    <PurgeChildEntries>true_to_purge_all_child_entries</PurgeChildEntries>
</InvalidateCache>
```

## \<InvalidateCache\> attributes

The following table describes attributes that are common to all policy parent elements:

| Attribute | Description | Default | Presence |
|---|---|---|---|
| `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name. | N/A | Required |
| `continueOnError` | Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. | false | Optional |
| `enabled` | Set to `true` to enforce the policy. Set to `false` to *turn off* the policy. The policy will not be enforced even if it remains attached to a flow. | true | Optional |
| `async` | This attribute is deprecated. | false | Deprecated |

## \<DisplayName\> element

Use in addition to the `name` attribute to label the policy in the
management UI proxy editor with a different, natural-language name.

```
<DisplayName>Policy Display Name</DisplayName>
```

| Default | N/A If you omit this element, the value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|

## \<CacheContext\>/\<APIProxyName\> element

Specifies the name of the application that added the cache entry.

```
<APIProxyName>application_that_added_the_entry</APIProxyName>
```

### Attributes

| Attribute | Description | Default | Presence | Type |
|---|---|---|---|---|
| ref | Variable with the application name. | N/A | Optional | String |

## \<CacheContext\> element

Specifies how to construct a cache key when a `Prefix` element value is not
specified, or to clear cache entries added by another API proxy.

```
<CacheContext>
  <APIProxyName ref="variable_name">application_that_added_the_entry</APIProxyName>
  <TargetName ref="variable_name">endpoint_for_which_data_was_cached</TargetName>
  <ProxyName ref="variable_name">proxy_for_which_data_was_cached</ProxyName>
</CacheContext>
```

Used to construct the CacheKey. Values for APIProxyName, ProxyName, and TargetName are
mandatory when a CacheKey prefix (that is, a custom prefix) is not used to clear cache entries
added by another API proxy.

## \<CacheKey\> element

Configures a unique pointer to a piece of data stored in the cache.

```
<CacheKey>
    <Prefix>*string*</Prefix>
    <KeyFragment ref="*variable_name*" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Required |
| **Type:** | N/A |

`<CacheKey>` constructs the name of each piece of data stored in the
cache.

At runtime, `<KeyFragment>` values are prepended with either the
`<Scope>` element value or `<Prefix>` value. For example, the
following results in a cache key of
`UserToken__apiAccessToken__`\<*value_of_client_id\>*:

```
<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>
```

You use the `<CacheKey>` element in conjunction with
`<Prefix>` and `<Scope>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

## \<CacheResource\> element

Specifies the cache where messages should be stored.

Omit this element completely if this policy (and your corresponding PopulateCache and
LookupCache policies) is using the included shared cache.

```
<CacheResource>cache_to_use</CacheResource>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | String |

For more about configuring caches, see [Creating and editing an environment
cache](https://docs.apigee.com/api-platform/cache/manage-caches-environment).

## \<CacheKey\>/\<KeyFragment\> element

Specifies a value that should be included in the cache key, creating a namespace for matching
requests to cached responses.

```
<KeyFragment ref="*variable_name*"/>
<KeyFragment>*literal_string*</KeyFragment>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | N/A |

This can be a key (a static name that you provide) or a value (a dynamic entry set by
referencing a variable). All specified fragments combined (plus the prefix) are concatenated to
create the cache key.

```
<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />
```

You use the `<KeyFragment>` element in conjunction with
`<Prefix>` and `<Scope>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

### Attributes

| Attribute | Description | Default | Presence | Type |
|---|---|---|---|---|
| ref | The variable from which to get the value. Should not be used if this element contains a literal value. | N/A | Optional | String |

## \<CacheKey\>/\<Prefix\> element

Specifies a value to use as a cache key prefix.

```
<Prefix>prefix_string</Prefix>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | String |

Use this value instead of `<Scope>` when you want to specify your own value
rather than a `<Scope>` -enumerated value. If defined,
`<Prefix>` prepends the cache key value for entries written to the cache. A
`<Prefix>` element value overrides a `<Scope>` element
value.

You use the `<Prefix>` element in conjunction with
`<CacheKey>` and `<Scope>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

## \<CacheContext\>/\<ProxyName\> element

Specifies the name of the proxy for which the data was cached.

```
<ProxyName>proxy_for_which_data_was_cached</ProxyName>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | String |

### Attributes

| Attribute | Description | Default | Presence | Type |
|---|---|---|---|---|
| ref | The variable from which to get the value. Should not be used if this element contains a literal value. | N/A | Optional | String |

## \<PurgeChildEntries\> element

> [!WARNING]
> **Warning:** There is a known issue related to this element. Setting `<PurgeChildEntries>` to true purges all cache values rather than only the `<KeyFragment>` values. See [Known Issues](https://docs.apigee.com/release/known-issues).

`true` to purge cache entries that share the value set by a
`<KeyFragment>` element configured for this policy. Values in other parts of the
cache key, such as in `<Prefix>` elements, are not considered.

Note that the `<KeyFragment>` element must be specified. If it is not,
setting true for `<PurgeChildEntries>` could result in purging all entries in
the cache.

Invalidating all of the cache entries of the same key fragment value can be a useful way to
purge multiple related entries at once.

```
<PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>
```

|---|---|
| **Default:** | false |
| **Presence:** | Optional |
| **Type:** | Boolean |

## \<Scope\> element

Enumeration used to construct a prefix for a cache key when a `<Prefix>`
element is not provided in the `<CacheKey>` element.

```
<Scope>*scope_enumeration*</Scope>
```

|---|---|
| **Default:** | "Exclusive" |
| **Presence:** | Optional |
| **Type:** | String |

The `<Scope>` setting determines a cache key that is prepended according to
the `<Scope>` value. For example, a cache key would take the following form when
scope is set to `Exclusive`:


*orgName__envName__**application**Name__deployedRevisionNumber__proxy\|TargetName__*
\[ *serializedCacheKey* \].

If a `<Prefix>` element is present in `<CacheKey>`, it
supersedes a `<Scope>` element value. Valid values include the enumerations
below.

You use the `<Scope>` element in conjunction with
`<CacheKey>` and `<Prefix>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

### Acceptable values

| Scope Value | Description |
|---|---|
| `Global` | Cache key is shared across all API proxies deployed in the environment. Cache key is prepended in the form *orgName* __ *envName* __. If you define a `<CacheKey>` entry with the `<KeyFragment>` apiAccessToken and a `<Global>` scope, each entry is stored as `orgName__envName__apiAccessToken`, followed by the serialized value of the access token. For an API proxy deployed in an environment called 'test' in an organization called 'apifactory', access tokens would be stored under the following cache key: `apifactory__test__apiAccessToken`. |
| `Application` | API proxy name is used as the prefix. Cache key is prepended in the form *orgName__envName__**application**Name*. |
| `Proxy` | ProxyEndpoint configuration is used as the prefix. Cache key is prepended in the form *orgName__envName__**application**Name__deployedRevisionNumber__proxyEndpointName* . |
| `Target` | TargetEndpoint configuration is used as the prefix. Cache key prepended in the form *orgName__envName__**application**Name__deployedRevisionNumber__targetEndpointName* . |
| `Exclusive` | Default. This is the most specific, and therefore presents minimal risk of namespace collisions within a given cache. Prefix is one of two forms: - If the policy is attached to the `ProxyEndpoint` flow, prefix is of the form *ApiProxyName_ProxyEndpointName*. - If the policy is attached at `TargetEndpoint`, prefix is of the form *ApiProxyName_TargetName*. Cache key prepended in the form *orgName__envName__**application**Name__deployedRevisionNumber__proxyNameITargetName* For example, the full string might look like this: ``` apifactory__test__weatherapi__16__default__apiAccessToken ``` . |

## \<CacheContext\>/\<TargetName\> element

Specifies the name of the target endpoint for which the data was cached.

```
<TargetName>endpoint_for_which_data_was_cached</TargetName>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | String |

### Attributes

| Attribute | Description | Default | Presence | Type |
|---|---|---|---|---|
| ref | The variable from which to get the value. Should not be used if this element contains a literal value. | N/A | Optional | String |

## Usage notes

General purpose caching with the [Populate Cache policy](https://docs.apigee.com/api-platform/reference/policies/populate-cache-policy), [LookupCache policy](https://docs.apigee.com/api-platform/reference/policies/lookup-cache-policy), and
InvalidateCache policy uses either a cache you configure or a shared cache that's included by
default. In most cases, the underlying shared cache should meet your needs. To use this cache,
simply omit the `<CacheResource>` element.

For more about configuring caches, see [Creating and editing an environment
cache](https://docs.apigee.com/api-platform/cache/manage-caches-environment). For more about the underlying data store, see [Cache internals](https://docs.apigee.com/api-platform/cache/cache-internals).

## Error codes


This section describes the error messages and flow variables that are set when this policy
triggers an error. This information is important to know if you are developing fault rules for a
proxy. To learn more, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).

### Error code prefix

N/A

### Runtime errors

This policy does not throw any runtime errors.

### Deployment errors

These errors can occur when you deploy a proxy containing this policy.

> [!IMPORTANT]
> Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

| Error name | Cause | Fix |
|---|---|---|
| `InvalidCacheResourceReference` | This error occurs if the `<CacheResource>` element in the InvalidateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/invalidate-cache-deployment-errors#invalidcacheresourcereference) |
| `CacheNotFound` | This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/invalidate-cache-deployment-errors#cachenotfound) |

### Fault variables

N/A

### Example error response

N/A

<br />