Quota policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

policy icon

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.

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.

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

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

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.

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.

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>

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.

<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:

 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.

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.

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.

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.

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 synchronize either after a time period or a message count, using either the <SyncIntervalInSeconds> or <SyncMessageCount> child elements. They are mutually exclusive. For example,

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

or

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

<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 across all nodes between quota updates.

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

This example specifies that the quota count is updated every 5 requests across each node.

<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.

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

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>

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:

<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.

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

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

{  
   "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>

Schemas

Related topics

ResetQuota policy

SpikeArrest policy

Comparing Quota and Spike Arrest policies