InvalidateCache policy

This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The InvalidateCache policy 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 thePopulateCache policy (for writing entries) and theLookupCache policy (for reading cache entries).

For caching the responses of backend resources, see theResponseCache policy.

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

Note: To clear a cache outside of a message flow without policies, you can use theDelete caches API.

Element reference

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

<InvalidateCacheasync="false"continueOnError="false"enabled="true"name="policy-name"><DisplayName>PolicyName</DisplayName><CacheKey><Prefix>prefix_string</Prefix><KeyFragmentref="variable_reference"/><KeyFragment>fragment_string</KeyFragment></CacheKey><!--Omitthiselementifyou'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:

AttributeDescriptionDefaultPresence
name

The internal name of the policy. The value of thename 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/ARequired
continueOnError

Set tofalse to return an error when a policy fails. This is expected behavior for most policies.

Set totrue to have flow execution continue even after a policy fails. See also:

falseOptional
enabled

Set totrue to enforce the policy.

Set tofalse toturn off the policy. The policy will not be enforced even if it remains attached to a flow.

trueOptional
async

This attribute is deprecated.

falseDeprecated

<DisplayName> element

Use in addition to thename 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'sname attribute is used.

PresenceOptional
TypeString

<CacheContext>/<APIProxyName> element

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

<APIProxyName>application_that_added_the_entry</APIProxyName>

Attributes

AttributeDescriptionDefaultPresenceType
refVariable with the application name.N/AOptionalString

<CacheContext> element

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

<CacheContext><APIProxyNameref="variable_name">application_that_added_the_entry</APIProxyName><TargetNameref="variable_name">endpoint_for_which_data_was_cached</TargetName><ProxyNameref="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><KeyFragmentref="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 ofUserToken__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, seeWorking with cache keys.

<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, seeGeneral purpose caching.

<CacheKey>/<KeyFragment> element

Specifies a value that should be included in the cache key. Specify a variable to de-reference with theref attribute, or a fixed value.

<KeyFragmentref="variable_name"/><KeyFragment>literal_string</KeyFragment>

Default:

N/A

Presence:

Optional

Type:

N/A

At runtime, Apigee creates the cache key by prepending the value obtained from the<Scope> element or the<Prefix> element, to a concatenation of the resolved values of each of the<KeyFragment> elements. For more information, seeWorking with cache keys.

Attributes

AttributeDescriptionDefaultPresenceType
refThe variable from which to get the value. Should not be used if this element contains a literal value.N/AOptionalString

<CacheKey>/<Prefix> element

Specifies a value to use as a cache key prefix.

<Prefix>prefix_string</Prefix>

Default:

N/A

Presence:

Optional

Type:

String

A<Prefix> element overrides any<Scope> element.

At runtime, Apigee creates the cache key by prepending the value obtained from the<Scope> element or the<Prefix> element, to a concatenation of the resolved values of each of the<KeyFragment> elements. For more information, seeWorking with cache keys.

<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

AttributeDescriptionDefaultPresenceType
refThe variable from which to get the value. Should not be used if this element contains a literal value.N/AOptionalString

<PurgeChildEntries> element

true to purge cache entries that share the same<Prefix> value configured for this policy, even if thePopulateCache policy instances that loaded those items into cache also used various<KeyFragment> elements.

Invalidating all of the cache entries of the same prefix value allows you 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 toExclusive:

orgName__envName__applicationName__proxy|TargetName__ [serializedCacheKey ].

If a<Prefix> element is present in<CacheKey>, it supersedes a<Scope> element value. Valid values for the<Scope> element are shown below.

For more information, seeWorking with cache keys.

Acceptable values

Scope ValueDescription
Global

Cache key is shared across all API proxies deployed in the environment. Cache key is prepended in the formorgName __envName __.

If you define a<CacheKey> entry with the<KeyFragment> apiAccessToken and a<Global> scope, each entry is stored asorgName__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 formorgName__envName__applicationName.

Proxy

ProxyEndpoint configuration is used as the prefix.

Cache key is prepended in the formorgName__envName__applicationName__proxyEndpointName .

Target

TargetEndpoint configuration is used as the prefix.

Cache key prepended in the formorgName__envName__applicationName__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 theProxyEndpoint flow, prefix is of the formApiProxyName_ProxyEndpointName.
  • If the policy is attached atTargetEndpoint, prefix is of the formApiProxyName_TargetName.

Cache key prepended in the formorgName__envName__applicationName__proxyNameITargetName

For example, the full string might look like this:

apifactory__test__weatherapi__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

AttributeDescriptionDefaultPresenceType
refThe variable from which to get the value. Should not be used if this element contains a literal value.N/AOptionalString

Usage notes

General purpose caching with thePopulateCache policy,LookupCache 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, seeGeneral purpose caching. For more about the underlying data store, seeCache 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, seeWhat you need to know about policy errors andHandling faults.

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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.
Error nameCauseFix
InvalidCacheResourceReferenceThis error occurs if the<CacheResource> element in theInvalidateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed.
CacheNotFoundThis error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component.

Fault variables

N/A

Example error response

N/A

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.