Quota policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Overview

A quota is an allotment of request messages that an API proxy can handle over a time period, such as minute, hour, day, week, or month. The Quota policy maintains counters that tally the number of requests received by the API proxy. This capability enables API providers to enforce limits on the number of API calls made by apps over an interval of time. Using Quota policies you can, for example, limit apps to 1 request per minute, or to 10,000 requests per month.

This policy is an Extensible 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, see Policy types.

Note: When an API proxy reaches its quota limit, subsequent API calls are rejected; Apigee returns an error message for every request that exceeds the quota. The Quota policy provides the ability to reset quotas on-the-fly, after an app has exceeded its limit.

For example, if a Quota is defined as 10,000 messages per month, rate-limiting begins after the 10,000th message. It doesn't matter whether 10,000 messages were counted on the first day or the last day of that period; no additional requests are allowed until the Quota counter automatically resets at the end of the specified time interval, or until the Quota is explicitly reset using the ResetQuota policy.

A variation on the Quota policy, SpikeArrest policy, prevents traffic spikes (or bursts) that can be caused by a sudden increase in usage, buggy clients, or malicious attacks.

Use the Quota policy to configure the number of request messages that an API proxy allows over a period of time, such as a minute, hour, day, week, or month. You can set the quota to be the same for all apps accessing the API proxy, or you can set the quota based on:

• The product that contains the API proxy
• The app requesting the API
• The app developer
• Many other criteria

Don't use the Quota policy to shield against overall traffic spikes. For that, use the SpikeArrest policy.

Tip: Need help deciding which rate limiting policy to use? See Comparing Quota and SpikeArrest policies.

Videos

Note: The following videos show the classic Proxy Editor in the Apigee UI. Apigee is introducing a new version of the Proxy Editor, which has a different design than the classic version shown in the videos.

These videos introduce quota management with the Quota policy:

Intro

Dynamic Quota

Distributed & Synchronous

Message Weight

Calendar

Rolling Window

Flexi

Conditional Quota

Flow Variables

Error Handling

Quota policy types

The Quota policy supports several different ways in which the quota counter starts and resets. You can define which to use with the type attribute on the <Quota> element, as the following example shows:

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

Valid values of type include:

• calendar: Configures a quota based on an explicit start time. The Quota counter for each app is refreshed based on the <StartTime>, <Interval>, and <TimeUnit> values that you set.
• rollingwindow: Configures a quota that uses a "rolling window" to determine quota usage. With rollingwindow, you determine the size of the window with the <Interval> and <TimeUnit> elements; for example, 1 day. When a request comes in, Apigee looks at the exact time of the request (say 5:01pm), counts the number of requests that came in between then and 5:01pm the previous day (1 day), and determines whether or not quota has been exceeded during that window.
• flexi: Configures a quota that causes the counter to begin when the first request message is received from an app, and resets based on the <Interval> and <TimeUnit> values.

The following table describes the quota resets for each type:

Time Unit	Type
	default (or null)	calendar	flexi
minute	Start of next minute	One minute after <StartTime>	One minute after first request
hour	Top of next hour	One hour after <StartTime>	One hour after first request
day	Midnight GMT of the current day	24 hours after <StartTime>	24 hours after first request
week	Midnight GMT Sunday at the end of the week	One week after <StartTime>	One week after first request
month	Midnight GMT of the last day of the month	One month (28 days) after <StartTime>	One month (28 days) after first request

Note: The Quota policy also supports second as the time unit. However, second is only supported for non-distributed counters, as defined by Distributed=false. Instead of using second, Google recommends that you use the SpikeArrest policy to limit spikes in request traffic at the second level.

For type="calendar", you must specify the value of <StartTime>.

The table does not list the value for the rollingwindow type. Rolling window quotas work by setting the size of a quota window, such as a one hour or one day window. When a new request comes in, the policy determines if the quota has been exceeded in the past window of time.

For example, you define a two hour window that allows 1000 requests. A new request comes in at 4:45 PM.The policy calculates the quota count for the past two hour window, meaning the number of requests since 2:45 PM. If the quota limit has not been exceeded in that two-hour window, then the request is allowed.

One minute later, at 4:46 PM, another request comes in. Now the policy calculates the quota count since 2:46 PM to determine if the limit has been exceeded.

For the rollingwindow type, the counter never resets, but is recalculated on each request.

Understanding quota counters

When a quota policy executes in an API proxy flow, a quota counter is decremented. When the counter reaches its limit, no further API calls associated with that counter are permitted. Depending on your configuration, the quota policy may employ one or more counters. It's important to understand when multiple counters are employed and how they behave.

How quotas are counted for API products

If your API proxy is included in an API product, you can configure the quota policy to use the quota rules that are defined in that product. An API product can specify quota rules at the product level or at the level of individual operations.

A separate quota counter is maintained for each operation defined in an API product, and the following rules are observed:

• If an operation has a quota defined for it, then the operation's quota rules take precedence over the quota rules defined at the product level. A separate quota counter is created for each operation. Any API calls to an operation's path increments its counter.
• If an operation does not have a quota defined for it, then the product-level quota rule is applied; however, a separate quota counter is still maintained for the operation. It is important to understand in this case that even though the quota rule is taken from the product-level definition, the operation still maintains its own counter.
• If the API product does not include any quota definitions -- neither at the product nor operation level -- quota rules specified in the policy apply; however, in this case, too, a separate quota counter is maintained for each operation in the API product.

The following sections describe counter options and behavior in more detail.

Configuring API proxy-level counters

It is possible to configure an API product to maintain a quota count at the API proxy scope. In this case, the quota configuration specified at the API product level is shared by all operations that do not have their own quota specified. The effect of this configuration is to create a global counter at the API proxy level for this API product.

To achieve this configuration, you must use the /apiproducts Apigee API to create or update the product and set the quotaCountScope attribute to PROXY in the create or update request. With the PROXY configuration, all the operations defined for the API product that are associated with the same proxy, and do not have their own counter, will share the same quota counter set at the API product level.

In Figure 1, Operation 1 and 2 are associated with Proxy1 and Operation 4 and 5 are associated with Proxy3. Because quotaCounterScope=PROXY is set in the API product, each of these operations share the API product-level quota setting. Note that while these operations share the same quota configuration, they use separate counters, based on their proxy association. On the other hand, Operation 3 has its own quota configuration set, and therefore is unaffected by the quotaCounterScope flag.

Figure 1: Use of the quotaCounterScope flag

If quotaCounterScope=PROXY, we recommend that you do not configure operations where some proxy resources have a quota configuration set and others do not. For example, in Figure 1, if Operation 4 has its own quota configuration and Operation 5 does not, that configuration is considered an anti-pattern.

By default, if an operation does not have a quota defined for it, then the product-level quota rule is applied; however, a separate quota counter is still maintained for the operation.

How quotas are counted if no API products are in use

If there is no API product associated with an API proxy, a quota policy maintains a single counter, regardless of how many times you reference it in an API proxy. The name of the quota counter is based on the name attribute of the policy.

For example, you create a Quota policy named MyQuotaPolicy with a limit of 5 requests and place it on multiple flows (Flow A, B, and C) in the API proxy. Even though it is used in multiple flows, it maintains a single counter that is updated by all instances of the policy:

• Flow A is executed -> MyQuotaPolicy is executed and its counter = 1
• Flow B is executed -> MyQuotaPolicy is executed and its counter = 2
• Flow A is executed -> MyQuotaPolicy is executed and its counter = 3
• Flow C is executed -> MyQuotaPolicy is executed and its counter = 4
• Flow A is executed -> MyQuotaPolicy is executed and its counter = 5

The next request to any of the three flows is rejected because the quota counter has reached its limit.

Using the same Quota policy in more than one place in an API proxy flow, which can unintentionally cause Quota to run out faster than you expected, is an anti-pattern described in Introduction to antipatterns.

Alternatively, you can define multiple Quota policies in your API proxy and use a different policy in each flow. Each Quota policy maintains its own counter, based on the name attribute of the policy.

Creating multiple counters through policy configuration

You can use the <Class> or <Identifier> elements in the Quota policy to define multiple, unique counters in a single policy. By using these elements, a single policy can maintain different counters based on the app making the request, the app developer making the request, a client ID or other client identifier, and more. See the examples above for more information on using the <Class> or <Identifier> elements.

Note: Quota counters are scoped to the API proxy that contains the Quota policy. If multiple API proxies contain Quota policies with the same name, the counters are maintained separately.

Time notation

All Quota times are set to the Coordinated Universal Time (UTC) time zone.

Quota time notation follows the international standard date notation defined in International Standard ISO 8601.

Dates are defined as year, month, and day, in the following format: YYYY-MM-DD. For example, 2021-02-04 represents February 4, 2021.

Time of day is defined as hours, minutes, and seconds in the following format: hours:minutes:seconds. For example, 23:59:59 represents the time one second before midnight.

Note that two notations, 00:00:00 and 24:00:00, are available to distinguish the two midnights that can be associated with one date. Therefore 2021-02-04 24:00:00 is the same date and time as 2021-02-05 00:00:00. The latter is usually the preferred notation.

Getting quota settings from the API product configuration

You can set quota limits in API product configurations. Those limits don't automatically enforce quota. Instead, you can reference product quota settings in a quota policy. Here are some advantages of setting a quota on the product for quota policies to reference:

• Quota policies can use a uniform setting across all API proxies in the API product.
• You can make runtime changes to the quota setting on an API product, and quota policies that reference the value automatically have updated quota values.

For more information on using quota settings from an API product, see the "Dynamic Quota" example above.

For info on configuring API products with quota limits, see Managing API products.

Configuring shared quota counters

Typically, the Quota policy counts all requests sent to an API proxy. For some use cases, you may wish to enforce the incoming request quota count, but also increment the quota count for target responses that meet a specified condition. Three Quota policy elements when used together, <SharedName>, <CountOnly>, and <EnforceOnly>, allow you to customize the Quota policy to enforce the incoming request quota and count target responses based on a condition that you specify.

For example, suppose you wish to increment the quota counter for an API proxy where the responses from the backend target have a 200 HTTP status code. To achieve this specialized counting, do the following:

• Add a Quota policy to the ProxyEndpoint Request flow with the <SharedName> element set with a name value and the <EnforceOnly> element set to true.
• Add another Quota policy to the ProxyEndpoint Response flow with the <SharedName> element set to the same name value as the first policy and the <CountOnly> element set to true.
• Place the second Quota policy (the one with <CountOnly>) in a conditional step that sets the condition upon which to increment the quota counter.

For an example showing how to use shared counters, see Shared counters in the Samples section.

Samples

These policy code samples illustrate how to start and end quota periods by:

More Dynamic Quota

<Quota name="CheckQuota">
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

Dynamic quotas enable you to configure a single Quota policy that enforces different quota settings based on information passed to the Quota policy. Another term for Quota settings in this context is service plan. The dynamic Quota checks the apps' service plan and then enforces those settings.

Note: If you specify both a value and a reference for an element, then reference gets the priority. If reference does not resolve at runtime, then the value is used.

For example, when you create an API product, you can optionally set the allowed quota limit, time unit, and interval. However, setting these value on the API product does not enforce their use in an API proxy. You must also add a Quota policy to the API proxy that reads these values. See Create API products for more.

In the example above, the API proxy containing the Quota policy uses a VerifyAPIKey policy, named verify-api-key, to validate the API key passed in a request. The Quota policy then accesses the flow variables from the VerifyAPIKey policy to read the quota values set on the API product.

Another option is to set custom attributes on individual developers or apps, and then read those values in the Quota policy. For example, to set different quota values per developer. you set custom attributes on the developer containing the limit, time unit, and interval. You then reference these values in the Quota policy as shown below:

<Quota name="DeveloperQuota">
  <Identifier ref="verifyapikey.verify-api-key.client_id"/>
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/>
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/>
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/>
</Quota>

This example also uses the VerifyAPIKey flow variables to reference the custom attributes set on the developer.

You can use any variable to set the parameters of the Quota policy. Those variables can come from:

• Flow variables
• Properties on the API product, app, or developer
• A key value map (KVM)
• A header, query parameter, form parameter, and others

For each API proxy, you can add a Quota policy that either references the same variable as all the other Quota policies in all the other proxies, or the Quota policy can reference variables unique for that policy and proxy.

Start time

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2021-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

For a Quota with type set to calendar, you must define an explicit <StartTime> value. The time value is the GMT time, not local time. If you do not provide a <StartTime> value for a policy of type calendar, Apigee issues an error.

The Quota counter for each app is refreshed based on the <StartTime>, <Interval>, and <TimeUnit> values. For this example, the Quota begins counting at 10:30 am GMT on February 18, 2021, and refreshes every 5 hours. Therefore, the next refresh is at 3:30 pm GMT on February 18, 2021.

Access Counter

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

An API proxy has access to the flow variables set by the Quota policy. You can access these flow variables in the API proxy to perform conditional processing, monitor the policy as it gets close to the quota limit, return the current quota counter to an app, or for other reasons.

Because access the flow variables for the policy is based on the policies name attribute, for the policy above named <Quota> you access its flow variables in the form:

• ratelimit.QuotaPolicy.allowed.count: Allowed count.
• ratelimit.QuotaPolicy.used.count: Current counter value.
• ratelimit.QuotaPolicy.expiry.time: UTC time when the counter resets.

There are many other flow variables that you can access, as described below.

For example, you can use the following AssignMessage policy to return the values of Quota flow variables as response headers:

<AssignMessage continueOnError="false" enabled="true" name="ReturnQuotaVars">
  <AssignTo createNew="false" type="response"/>
  <Set>
    <Headers>
      <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
      <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
      <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Shared counters

The following example illustrates how to configure a shared counter for an API proxy, where the quota counter is also incremented when the target response is HTTP status 200. Because both the Quota policies use the same <SharedName> value, both of the Quota policies will share the same quota counter. For more information, see Configuring shared quota counters.

ProxyEndpoint configuration example:

<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>Enforce-Only</Name>  <!--First quota policy enforces quota count -->
            </Step>
        </Request>
        <Response>
            <Step>
                <Name>Count-Only</Name>   <!-- Second quota policy counts quota if call is successful -->
                <Condition>response.status.code = 200</Condition>
            </Step>
        </Response>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/quota-shared-name</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

First quota policy example:

<Quota continueOnError="false" enabled="true" name="Enforce-Only" type="rollingwindow">
    <DisplayName>Enforce-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <EnforceOnly>true</EnforceOnly>
    <SharedName>common-proxy</SharedName>  <!-- Notice that SharedName value is the same for both Quota policies -->
</Quota>

Second Quota policy example:

<Quota continueOnError="false" enabled="true" name="Count-Only" type="rollingwindow">
    <DisplayName>Count-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <CountOnly>true</CountOnly>
    <SharedName>common-proxy</SharedName>  <!-- Same name as the first policy -->
</Quota>

Note: You cannot use both the <Class> and <Identifier> elements in the same Quota policy.

First Request

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

Use this sample code to enforce a quota of 10,000 calls per one hour. The policy resets the quota counter at the top of each hour. If the counter reaches the 10,000-call quota before the end of the hour, calls beyond 10,000 are rejected.

For example, if the counter starts at 2021-07-08 07:00:00, then it resets to 0 at 2021-07-08 08:00:00 (1 hour from the start time). If the first message is received at 2021-07-08 07:35:28 and the message count reaches 10,000 before 2021-07-08 08:00:00, calls beyond that count are rejected until the count resets at the top of the hour.

The counter reset time is based on the combination of <Interval> and <TimeUnit>. For example, if you set <Interval> to 12 for a <TimeUnit> of hour, then the counter resets every twelve hours. You can set <TimeUnit> to minute, hour, day, week, or month.

You can reference this policy in multiple places in your API proxy. For example, you could place it on the Proxy PreFlow so it is executed on on every request. Or, you could place it on multiple flows in the API proxy. If you use this policy in multiple places in the proxy, it maintains a single counter that is updated by all instances of the policy.

Alternatively, you can define multiple Quota policies in your API proxy. Each Quota policy maintains its own counter, based on the name attribute of the policy.

Set identifier

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2021-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

By default, a Quota policy defines a single counter for the API proxy, regardless of the origin of a request. Alternatively, you can use the <Identifier> attribute with a Quota policy to maintain separate counters based on the value of the <Identifier> attribute.

For example, use the <Identifier> tag to define separate counters for every client ID. On a request to your proxy, the client app then passes a header containing the clientID, as shown in the example above.

You can specify any flow variable to the <Identifier> attribute. For example, you could specify that a query param named id contains the unique identifier:

<Identifier ref="request.queryparam.id"/>

If you use the VerifyAPIKey policy to validate the API key, or the OAuthV2 policies with OAuth tokens, you can use information in the API key or token to define individual counters for the same Quota policy. For example, the following <Identifier> element uses the client_id flow variable of a VerifyAPIKey policy named verify-api-key:

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

Each unique client_id value now defines its own counter in the Quota policy.

Class

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

You can set Quota limits dynamically by using a class-based Quota count. In this example, the quota limit is determined by the value of the developer_segment header passed with each request. That variable can have a value of platinum or silver. If the header has an invalid value, the policy returns a quota violation error.

Note: You cannot use both the <Class> and <Identifier> elements in the same Quota policy.

---

<Quota> element

Following are attributes and child elements of <Quota>. Note that some element combinations are mutually exclusive or not required. See the samples for specific usage.

The verifyapikey.my-verify-key-policy.apiproduct.* variables below are available by default when a VerifyAPIKey policy called my-verify-key-policy is used to check the app's API key in the request. The variable values come from the quota settings on the API product that the key is associated with, as described in Getting quota settings from the API product configuration.

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <Allow>
          <Class ref="request.queryparam.time_variable">
            <Allow class="peak_time" count="5000"/>
            <Allow class="off_peak_time" count="1000"/>
          </Class>
       </Allow>
       <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

The following attributes are specific to this policy:

Attribute	Description	Default	Presence
type	Sets the Quota policy type, which determines when and how the quota counter checks quota usage as well as how it resets. If you don't set type, the counter begins at the beginning of the minute/hour/day/week/month. Valid values include: calendar rollingwindow flexi For a complete description of each type, see Quota policy types.	N/A	Optional

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. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	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

<Allow>

Specifies the count limit for the quota. If the counter for the policy reaches this limit value, subsequent calls are rejected until the counter resets.

Can also contain a <Class> element that conditionalizes the <Allow> element based on a flow variable.

Default Value	n/a
Required?	Optional
Type	Integer or Complex type
Parent Element	<Quota>
Child Elements	<Class>

Shown below are three ways to set the <Allow> element:

<Allow count="2000"/>

<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>

<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

If you specify both count and countRef, then countRef gets the priority. If countRef does not resolve at runtime, then the value of count is used.

You can also specify a <Class> element as a child of <Allow> to determine the allowed count of the policy based on a flow variable. Apigee matches the value of the flow variable to the class attribute of the <Allow> element, as shown below:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

The following table lists attributes of <Allow>:

Attribute	Description	Default	Presence
count	Use to specify a message count for the quota. For example, a count attribute value of 100, Interval of 1, and a TimeUnit of month specify a quota of 100 messages per month.	2000	Optional
countRef	Use to specify a flow variable containing the message count for a quota. countRef takes precedence over the count attribute.	none	Optional

<Class>

Lets you conditionalize the value of the <Allow> element based on the value of a flow variable. For each different <Allow> child tag of <Class>, the policy maintains a different counter.

Default Value	n/a
Required?	Optional
Type	Complex type
Parent Element	<Allow>
Child Elements	<Allow> (child of <Class>)

To use the <Class> element, specify a flow variable using the ref attribute to the <Class> element. Apigee then uses the value of the flow variable to select one of the <Allow> child elements to determine the allowed count of the policy. Apigee matches the value of the flow variable to the class attribute of the <Allow> element, as shown below:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

In this example, the current quota counter is determined by the value of the time_variable query param passed with each request. That variable can have a value of peak_time or off_peak_time. If the query param contains an invalid value, the policy returns a quota violation error.

Note: You cannot use both the <Class> and <Identifier> elements in the same Quota policy.

The following table lists attributes of <Class>:

Attribute	Description	Default	Presence
ref	Use to specify a flow variable containing the quota class for a quota.	none	Required

<Allow> (child of <Class>)

Specifies the limit for a quota counter defined by the <Class> element. For each different <Allow> child tag of <Class>, the policy maintains a different counter.

Default Value	n/a
Required?	Optional
Type	Complex type
Parent Element	<Class>
Child Elements	None

For example:

    <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow count="5000"/>
        <Allow count="1000"/>
      </Class>
    </Allow>

In this example, the Quota policy maintains two quota counters named peak_time and off_peak_time. Which of these is used depends on the query parameter passed in, as shown in <Class> example.

The following table lists attributes of <Allow>:

Attribute	Description	Default	Presence
class	Defines the name of the quota counter.	none	Required
count	Specifies the quota limit for the counter.	none	Required

<Interval>

Specifies the number of time periods in which quotas are calculated.

Default Value	n/a
Required?	Required
Type	Integer
Parent Element	<Quota>
Child Elements	None

Use to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the <TimeUnit> element you specify (minute, hour, day, week, or month) to determine a time period during which Apigee calculates quota use.

For example, an interval of 24 with a <TimeUnit> of hour means that the quota will be calculated over the course of 24 hours.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

The following table lists attributes of <Interval>:

Attribute	Description	Default	Presence
ref	Use to specify a flow variable containing the interval for a quota. ref takes precedence over an explicit interval value. If both reference and value are specified, then reference gets the priority. If ref does not resolve at runtime, then the value is used.	none	Optional

<TimeUnit>

Specifies the unit of time applicable to the quota.

Default Value	n/a
Required?	Required
Type	String
Parent Element	<Quota>
Child Elements	None

Select from minute, hour, day, week, month, or year.

Note: The Quota policy also supports second as the time unit. However, second is only supported for non-distributed counters (when <Distributed> is set to false). Google recommends that you use the SpikeArrest policy to limit spikes in request traffic at the second level rather than use the second value here.

For example, an Interval of 24 with a TimeUnit of hour means that the quota will be calculated over the course of 24 hours.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

Default:	none
Presence:	Required
Type:	String

The following table lists attributes of <TimeUnit>:

Attribute	Description	Default	Presence
ref	Specifies a flow variable containing the time unit for a quota. ref takes precedence over an explicit interval value. If ref does not resolve at runtime, then the interval value is used.	none	Optional

<StartTime>

When type is set to calendar, specifies the date and time when the quota counter begins counting, regardless of whether any requests have been received from any apps.

Default Value	n/a
Required?	Optional (Required when type is set to calendar)
Type	String in ISO 8601 date and time format
Parent Element	<Quota>
Child Elements	None

You must provide an explicit <StartTime> when type is set to calendar; you cannot use a reference to a flow variable. If you specify a <StartTime> value when no type value is set, then Apigee returns an error.

For example:

<StartTime>2021-7-16 12:00:00</StartTime>

<Distributed>

Determines whether Apigee uses one or more nodes to process requests.

Default Value	false
Required?	Optional
Type	Boolean
Parent Element	<Quota>
Child Elements	None

Set to true to specify that the policy should maintain a central counter and continuously synchronize it across all nodes. The nodes can be across availability zones and/or regions.

Note: If you have a paid Apigee account, you typically have multiple Message Processors in your installation, and that number can vary based on your traffic load. Evaluation accounts typically have two Message Processors.

If you use the default value of false, then you might exceed your quota because the count for each node is not shared:

<Distributed>false</Distributed>

To guarantee that the counters are synchronized, and updated on every request, set <Distributed> and <Synchronous> to true:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

Determines whether to update a distributed quota counter synchronously.

Default Value	false
Required?	Optional
Type	Boolean
Parent Element	<Quota>
Child Elements	None

Set to true to update a distributed quota counter synchronously. This means that the updates to the counters are made at the same time the quota is checked on a request to the API. Set to true if it is essential that you not allow any API calls over the quota.

Note: By implementing synchronous updates to the counter, there is the potential for performance impacts and lower throughputs. In some cases, use of <Synchronous>true</Synchronous> could cause the quota policy to fail to process some transactions.

Set to false to update the quota counter asynchronously. This means that it is possible that some API calls exceeding the quota will go through, depending on when the quota counter in the central repository is asynchronously updated. However, you will not face the potential performance impacts associated with synchronous updates.

The default asynchronous update interval is 10 seconds. Use the <AsynchronousConfiguration> element to configure this asynchronous behavior.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configures the synchronization interval among distributed quota counters when the policy configuration element <Synchronous> is either not present or present and set to false. Apigee ignores this element when <Synchronous> is set to true.

Default Value	n/a
Required?	Optional
Type	Complex type
Parent Element	<Quota>
Child Elements	<SyncIntervalInSeconds> <SyncMessageCount>

You can specify the synchronization behavior using the <SyncIntervalInSeconds> or <SyncMessageCount> child elements. Use either or both elements. For example,

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

or

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

• When only <SyncIntervalInSeconds> is present, the quota synchronizes every N seconds, where N is the value specified in the element, irrespective of how many messages have been handled.
• When only <SyncMessageCount> is present, the quota synchronizes every M messages, where M is the value specified in the element, or every 10 seconds, whichever comes first.
• When both elements are present, the quota synchronizes every M messages or every N seconds, whichever comes first.
• When <AsynchronousConfiguration> is not present or neither child element is present, the quota synchronizes every 10 seconds, irrespective of how many messages have been handled.

<SyncIntervalInSeconds>

Overrides the default behavior in which asynchronous updates are performed after an interval of 10 seconds.

Default Value	10 seconds
Required?	Optional
Type	Integer
Parent Element	<AsynchronousConfiguration>
Child Elements	None

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

The sync interval must be >= 10 seconds, as described in Limits.

<SyncMessageCount>

Specifies the number of requests to process before synchronizing the quota counter.

Default Value	n/a
Required?	Optional
Type	Integer
Parent Element	<AsynchronousConfiguration>
Child Elements	None

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Using the configuration in this example, on each node, the quota count will synchronize after every 5 requests, or every 10 seconds, whichever comes first.

<Identifier>

Configures the policy to create unique counters based on a flow variable.

Default Value	n/a
Required?	Optional
Type	String
Parent Element	<Quota>
Child Elements	None

Via the Identifier element, you can allot call counts to distinct buckets defined by the value in a flow variable. For example, you can use the developer.id variable, which is populated after a VerifyAPIKey policy, to enforce one quota limit to all instances of all apps created by each specific developer, or you can use the client_id to enforce a quota limit for each particular app. The configuration for the latter looks like this:

<Identifier ref="client_id"/>

You can refer to either a custom variable that you might set with the AssignMessage policy or the JavaScript policy, or a variable that is implicitly set, such as those set by the VerifyAPIKey policy or the VerifyJWT policy. For more on variables, see Using Flow Variables, and for a list of well-known variables defined by Apigee, see the Flow variables reference.

If you don't use this element, the policy allots all call counts into a single counter for the particular Quota policy.

If you refer to developer.id or developer.app.id for the quota <Identifier>, or use those variables as one element in a custom variable used as the <Identifier>, be aware that the values of these variables may change, during some future maintenance period. This would be rare, not a regular occurrence. But if it were to occur, and if you had a Quota policy using one of those variables as the <Identifier>, then the quota wouldn't be strictly enforced during the time window in which the change occurred.

This element is also discussed in How does the Quota policy work when no Identifier is specified?

Note: You cannot use both the <Class> and <Identifier> elements in the same Quota policy.

The following table describes the attributes of <Identifier>:

Attribute	Description	Default	Presence
ref	Specifies a flow variable that identifies the counter to use for the request. The variable can refer to an HTTP header, a query parameter, a form parameter, or an element of the message content, or, some other value to identify how to allot call counts. The client_id is commonly used as the variable. The client_id is also known as the API key or consumer key, and is generated for an app when it is registered in an organization on Apigee. You can use this identifier if you have enabled API key or OAuth authorization policies for your API.	N/A	Optional

<MessageWeight>

Specifies the cost assigned to each message for quota purposes. Use this element to increase impact of request messages that, for example, consume more computational resources than others.

Default Value	n/a
Required?	Optional
Type	Integer
Parent Element	<Quota>
Child Elements	None

For example, you want to count POST messages as being twice as expensive as GET messages. Therefore, you set the <MessageWeight> to 2 for a POST and 1 for a GET. You can even set the <MessageWeight> to 0 so the request does not affect the counter.

In this example, if the quota is 10 messages per minute and the <MessageWeight> for POST requests is 2, then the quota will permits 5 POST requests in any 10 minute interval. Any additional request, POST or GET, before the counter resets are rejected.

A value representing <MessageWeight> must be specified by a flow variable, and can be extracted from HTTP headers, query parameters, an XML or JSON request payload, or any other flow variable. For example, you set it in a header named weight:

<MessageWeight ref="message_weight"/>

<UseQuotaConfigInAPIProduct>

Defines quota settings for an API product, such as the time units, interval, and allowed maximum.

Default Value	n/a
Required?	Optional
Type	Complex type
Parent Element	<Quota>
Child Elements	<DefaultConfig>

If you add the <UseQuotaConfigInAPIProduct> element to the Quota policy, then Apigee ignores any <Allow>, <Interval>, and <TimeUnit> child elements of <Quota>.

The <UseQuotaConfigInAPIProduct> element is simply a container for the default settings that you define using the <DefaultConfig> element, as the following example shows:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

You can use the stepName attribute to reference either a VerifyAPIKey policy or a ValidateToken policy operation of the OAuthv2 policy in the flow.

The following table describes the attributes of <UseQuotaConfigInAPIProduct>:

Attribute	Description	Default	Presence
stepName	Identifies the name of the authentication policy in the flow. The target can be either a VerifyAPIKey policy or an OAuthv2 policy.	N/A	Required

For more information, see the following:

• <DefaultConfig>
• What is an API product?
• Managing API products

<DefaultConfig>

Contains default values for an API product's quota. When you define a <DefaultConfig>, all three child elements are required.

Default Value	n/a
Required?	Optional
Type	Complex type
Parent Element	<UseQuotaConfigInAPIProduct>
Child Elements	<Allow> <Interval> <TimeUnit>

It's possible to define these values on both the API product's operation (either with the UI or the API products API and in the Quota policy. If you do that, however, the settings on the API product take precedence and the settings on the Quota policy are ignored.

The syntax for this element is as follows:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

The following example specifies a quota of 10,000 every week:

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

For more information, see the following:

• What is an API product?
• Managing API products

<SharedName>

Identifies this Quota policy as shared. All Quota policies in an API proxy with the same <SharedName> value share the same underlying quota counter. If this element is present, the <EnforceOnly> or <CountOnly> elements must also be present.

For more information and examples, see Configuring shared quota counters.

Default Value	n/a
Required?	Optional
Type	String
Parent Element	<Quota>
Child Elements	None

<CountOnly>

Place a Quota policy with this element set to true in a conditional step in the ProxyEndpoint response flow to conditionally increment the underlying quota counter. If this element is present, the <SharedName> and <EnforceOnly> elements must also be present.

For more information and examples, see Configuring shared quota counters.

Default Value	false
Required?	Optional
Type	Boolean
Parent Element	<Quota>
Child Elements	None

<EnforceOnly>

Place a Quota policy with this element set to true in the request flow of an API proxy. This configuration allows quota counts to be shared for any Quota policy in the API proxy with the same <SharedName> value. If this element is present, the <SharedName> and <CountOnly> elements must also be present.

For more information and examples, see Configuring shared quota counters.

Default Value	false
Required?	Optional
Type	Boolean
Parent Element	<Quota>
Child Elements	None

Flow variables

The following predefined Flow variables are automatically populated when a Quota policy executes. For more information, see Flow variables reference.

Variables	Type	Permissions	Description
ratelimit.{policy_name}.allowed.count	Long	Read-Only	Returns the allowed quota count.
ratelimit.{policy_name}.used.count	Long	Read-Only	Returns the current quota used within a quota interval.
ratelimit.{policy_name}.available.count	Long	Read-Only	Returns the available quota count in the quota interval.
ratelimit.{policy_name}.exceed.count	Long	Read-Only	Returns 1 after the quota is exceeded.
ratelimit.{policy_name}.total.exceed.count	Long	Read-Only	Returns 1 after the quota is exceeded.
ratelimit.{policy_name}.expiry.time	Long	Read-Only	Returns the UTC time (in milliseconds), which determines when the quota expires and when the new quota interval starts. When the Quota policy's type is rollingwindow, this value is not valid because the quota interval never expires.
ratelimit.{policy_name}.identifier	String	Read-Only	Returns the (client) identifier reference attached to the policy
ratelimit.{policy_name}.class	String	Read-Only	Returns the class associated with the client identifier
ratelimit.{policy_name}.class.allowed.count	Long	Read-Only	Returns the allowed quota count defined in the class
ratelimit.{policy_name}.class.used.count	Long	Read-Only	Returns the used quota within a class
ratelimit.{policy_name}.class.available.count	Long	Read-Only	Returns the available quota count in the class
ratelimit.{policy_name}.class.exceed.count	Long	Read-Only	Returns the count of requests that exceeds the limit in the class in the current quota interval
ratelimit.{policy_name}.class.total.exceed.count	Long	Read-Only	Returns the total count of requests that exceeds the limit in the class across all quota intervals, so it is the sum of class.exceed.count for all quota intervals.
ratelimit.{policy_name}.failed	Boolean	Read-Only	Indicates whether or not the policy failed (true or false).

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
policies.ratelimit.FailedToResolveQuotaIntervalReference	500	Occurs if the <Interval> element is not defined within the Quota policy. This element is mandatory and used to specify the interval of time applicable to the quota. The time interval can be minutes, hours, days, weeks, or months as defined with the <TimeUnit> element.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference	500	Occurs if the <TimeUnit> element is not defined within the Quota policy. This element is mandatory and used to specify the unit of time applicable to the quota. The time interval can be in minutes, hours, days, weeks, or months.
policies.ratelimit.InvalidMessageWeight	500	Occurs if the value of the <MessageWeight> element specified through a flow variable is invalid (a non-integer value).
policies.ratelimit.QuotaViolation	500	The quota limit was exceeded.	N/A

Deployment errors

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidQuotaInterval	If the quota interval specified in the <Interval> element is not an integer, then the deployment of the API proxy fails. For example, if the quota interval specified is 0.1 in the <Interval> element, then the deployment of the API proxy fails.
InvalidQuotaTimeUnit	If the time unit specified in the <TimeUnit> element is unsupported, then the deployment of the API proxy fails. The supported time units are minute, hour, day, week, and month.
InvalidQuotaType	If the type of the quota specified by the type attribute in the <Quota> element is invalid, then the deployment of the API proxy fails. The supported quota types are default, calendar, flexi, and rollingwindow.
InvalidStartTime	If the format of the time specified in the <StartTime> element is invalid, then the deployment of the API proxy fails. The valid format is yyyy-MM-dd HH:mm:ss, which is the ISO 8601 date and time format. For example, if the time specified in the <StartTime> element is 7-16-2017 12:00:00 then the deployment of the API proxy fails.
StartTimeNotSupported	If the <StartTime> element is specified whose quota type is not calendar type, then the deployment of the API proxy fails. The <StartTime> element is supported only for the calendar quota type. For example, if the type attribute is set to flexi or rolling window in the <Quota> element, then the deployment of the API proxy fails.
InvalidTimeUnitForDistributedQuota	If the <Distributed> element is set to true and the <TimeUnit> element is set to second then the deployment of the API proxy fails. The timeunit second is invalid for a distributed quota.
InvalidSynchronizeIntervalForAsyncConfiguration	If the value specified for the <SyncIntervalInSeconds> element within the <AsynchronousConfiguration> element in a Quota policy is less than zero, then the deployment of the API proxy fails.
InvalidAsynchronizeConfigurationForSynchronousQuota	If the value of the <AsynchronousConfiguration> element is set to true in a Quota policy, which also has asynchronous configuration defined using the <AsynchronousConfiguration> element, then the deployment of the API proxy fails.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	ratelimit.QT-QuotaPolicy.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Example fault rule

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Note: Currently, the Quota policy returns a status code of 500 when it enforces a rate limit. If you use the Apigee-managed service, and you would like to have your Quota policy return 429, contact Google Cloud Customer Care. to have the features.isHTTPStatusTooManyRequestEnabled property enabled. See Http 429 as default status code for Quota policy violation for additional details.

Note: When updating properties, you must pass all existing properties to the API, even if they are not being changed. If you omit properties in the payload, the properties are removed.

curl -u email:password -X POST -H "Content-type:application/xml" \
  http://LOAD_BALANCER_IP:8080/v1/o/myorg \
  -d '<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Environments/>
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
    </Properties>
  </Organization>'

Schemas

Sample: See our GitHub repository samples for the most recent schemas.

Related topics

ResetQuota policy

SpikeArrest policy

Comparing Quota and Spike Arrest policies