Send Docs Feedback

Quota policy

What

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 Quota to shield against overall traffic spikes. For that, use the Spike Arrest policy. See Spike Arrest policy.

Need help deciding which rate limiting policy to use? See Comparing Quota, Spike Arrest, and Concurrent Rate Limit Policies.

Where

While you can attach this policy anywhere in the flow, we recommend that you attach it in one of the following locations so that it can immediately check the quota count before allowing the message flow to continue.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

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

<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. For more on VerifyAPIKey flow variables, see Verify API Key policy.

Another option is to set custom attributes on individual developers or apps, and then read those values in the Quota policy. For example, you want to set different quota values per developer. In this case, 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 KVM or vault
  • A header, query parameter, form parameter, etc

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

<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 2014-07-08 07:00:00, then it resets to 0 at 2014-07-08 08:00:00 (1 hour from the start time). If the first message is received at 2014-07-08 07:35:28 and the message count reaches 10,000 before 2014-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.

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2014-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, Edge 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, 2014, and refreshes every 5 hours. Therefore, the next refresh is at 3:30 pm GMT on February 18, 2014. 

<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 QuotaPolicy 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 async="false" 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>  
<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/> 
  <StartTime>2014-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> tag 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.

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

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


About the Quota policy

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

When an API proxy reaches its Quota limit, subsequent API calls are rejected; Apigee Edge 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 area allowed until the Quota counter automatically resets at the end of the specified time interval, or until the Quota is explicitly reset using Reset Quota policy.

A variation on Quota called SpikeArrest prevents traffic spikes (or bursts) that can be caused by a sudden increase in usage, buggy clients, or malicious attacks. For more information on SpikeArrest, see Spike Arrest policy.

Quotas apply to individual API proxies and are not distributed among API proxies. For example, if you have three API proxies in an API product, a single quota is not shared across all three even if all three use the same quota policy configuration.

Quota policy types

The Quota policy supports several different types of policies: default, calendar, flexi, and rollingwindow. Each type defines when the quota counter starts and when it resets, as shown in the following table:

Time Unit Default (or null) reset calendar reset flexi reset
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 after <StartTime> One month 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

By default, 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.

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

Or, use the  <Class> or <Identifier> elements in the same Quota policy to define unique counters in the same policy. By using these elements in a Quota policy, 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.

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, 2015-02-04 represents February 4, 2015.

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 2015-02-04 24:00:00 is the same date and time as 2015-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 Create API products.

Element reference

Following are elements and attributes you can configure on this policy. Note that some element combinations are mutually exclusive or not required. See the samples for specific usage.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="request.header.allowed_quota"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="request.header.quota_count">1</Interval>
   <TimeUnit ref="request.header.quota_timeout">month</TimeUnit> 
   <StartTime>2014-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

<Quota> attributes

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

The following attributes are specific to this policy.

Attribute Description Default Presence
type

Use to set when the quota counter starts counting usage. See the table above for more information.

If you omit a type value, the default counter begins when the first request message is received from an app. 

Valid values include:

  • calendar: Configure 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: Configure a quota that uses a "rolling window" counter that advances by the time interval that you specify. The counter starts when the first message is received from the client plus the interval that you define. 
  • flexi: Configure 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.
null Optional

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

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

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<Allow> element

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. 

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

<Allow count="2000"/> 
<Allow countRef="request.header.allowed_quota"/> 
<Allow count="2000" countRef="request.header.allowed_quota"/> 

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.

Default: N/A
Presence: Optional
Type: Integer

Attributes

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

<Allow>/<Class> element

The <Class> element 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.

To use the <Class> element, specify a flow variable using the ref attribute to the <Class> tag. Edge then uses the value of the flow variable to select one of the <Allow> child tags to determine the allowed count of the policy. Edge matches the value of the flow variable to the class attribute of the <Allow> tag, 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.

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

Default: N/A
Presence: Optional
Type: N/A

Attributes

Attribute Description Default Presence
ref

Use to specify a flow variable containing the quota class for a quota.

none Required

<Allow>/<Class>/<Allow> element

The <Allow> element 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.

For example:

<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 Quota policy maintains two quota counters named of peak_time and off_peak_time.

Default: N/A
Presence: Optional
Type: N/A

Attributes

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

Use to specify the interval of time (in minutes, hours, days, weeks, or months as defined by TimeUnit) applicable to the quota.

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

<Interval ref="request.header.quota_count">1</Interval>
Default: none
Presence: Required
Type: Integer

Attributes

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

Use to specify the unit of time applicable to the quota.

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="request.header.quota_timeout">month</TimeUnit>
Default: none
Presence: Required
Type:

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

Attributes

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

<StartTime> element

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

You must provide an explicit StartTime when type is explicitly 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 you receive an error.

For example:

<StartTime>2014-7-16 12:00:00</StartTime>
Default: none
Presence: Required when type is set to calendar.
Type:

String in ISO 8601 date and time format.

<Distributed> element

An installation of Edge can use one or more Message Processors to process requests. Set this element to true to specify that the policy should maintain a central counter and continuously synchronize it across all Message Processors.

If you are an Edge Cloud customer, contact Apigee Support to determine the number of Message Processors in your installation. Free Edge accounts typically have two Message Processors.

If you are an Edge for Private Cloud customer, contact your Edge system administrator to determine the number of Message Processors.

For example, if the quota limit is 10 messages per hour, and two Message Processors are being used, the quota count total is continuously updated by both Message Processors.

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

<Distributed>true</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>
Default: false
Presence: Optional
Type: Boolean

<Synchronous> element

Set to true to update a distributed quota counter synchronously. This means that the update to the counter 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.

Know that by implementing synchronous updates to the counter, there is the potential for performance impacts and lower throughputs.

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>
Default: false
Presence: Optional
Type: Boolean

<AsynchronousConfiguration> element

Configures the synchronization interval amongst distributed quota counters when the policy is configured to make calls asynchronously (meaning when <Synchronous> is set to false).

You can synchronize either after a time period or a message count, using either the SyncIntervalInSeconds or SyncMessageCount child elements. They are mutually exclusive.

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
<!-- or -->
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
Default: 10 seconds
Presence: Optional, except when <Synchronous> is set to false.
Type:

Integer

<AsynchronousConfiguration>/<SyncIntervalInSeconds> element

Use to override the default asynchronous update interval of 10 seconds enforced by the AsynchronousConfiguration element.

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>
Default: 10
Presence: Optional
Type:

Integer

<AsynchronousConfiguration>/<SyncMessageCount> element

Use to override the default asynchronous update interval of 10 seconds enforced by the AsynchronousConfiguration element.

SyncMessageCount specifies the number of requests across all Apigee message processors between quota updates.

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

This example specifies that the quota count is updated every 5 requests across all Apigee message processors.

Default: none
Presence: Optional
Type:

Integer

<Identifier> element

Use the <Identifier> element to configure the policy to create unique counters based on a flow variable. You can create unique counters for different apps, API products, developers, or any other characteristic defined by a flow variable. You can use a variety of variables to indicate a unique developer or app, whether you're using custom variables or predefined variables, such as those available with the Verify API Key policy. See also the Variables reference.

If you don't use this element, the policy uses a single counter that is applied against the quota.

This element is also discussed in the following Apigee Community post: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

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

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

Default: N/A
Presence: Optional
Type:

String

Attributes

Attribute Description Default Presence
ref

Specifies a flow variable that identifies the counter to use for the request. The identifier can be an HTTP header, query parameter, form parameter, or message content that is unique to each app, app user, app developer, API product, or other characteristic.

The <Identifier> most commonly used to uniquely identify apps is the client_id. The client_id is another name for the API key, or consumer key, that is generated for an app when it is registered in an organization on Apigee Edge. You can use this identifier if you have enabled API key or OAuth authorization policies for your API.

In some circumstances, Quota settings must be retrieved where no client_id is available, such as when no security policy is in place. In those situations, you can use the Access Entity policy to retrieve the appropriate API product settings. For more information, see Access Entity policy.

N/A Optional

<MessageWeight> element

Use to specify the weight assigned to each message. Use message weight to increase impact of request messages that, for example, consume more computational resources than others.

For example, you want to count POST messages as being twice as "heavy" or 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 additianal 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="request.header.weight"/>
Default: N/A
Presence: Optional
Type:

Integer

Flow variables

The following predefined Flow variables are automatically populated when a Quota policy executes. For more information about Flow variables, see 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 counter
ratelimit.{policy_name}.exceed.count Long Read-Only Returns the count that exceeds the limit in the current counter
ratelimit.{policy_name}.total.exceed.count Long Read-Only Returns the total count that exceeds the limit, because the quota policy is attached
ratelimit.{policy_name}.expiry.time Long Read-Only

Returns the UTC time in milliseconds which determines when the quota expires and new quota counter starts.

When the Quota policy type is rollingwindow, this value is not valid because the quota count 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 that exceeds the limit in the class
ratelimit.{policy_name}.class.total.exceed.count Long Read-Only Returns the total count that exceeds the limit in the class, because the Quota policy is attached

Error codes

The format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The Quota policy type defines the following error codes. For guidance on handling errors, see Fault handling.

Error Code Message
QuotaViolation

Rate limit quota violation. Quota limit exceeded.

InvalidMessageWeight Invalid message weight value {0}
ErrorLoadingProperties Error loading rate limit properties from {0}
FailedToResolveQuotaIntervalReference Failed to resolve quota interval reference {0} in quota policy {1}
InvalidQuotaInterval Invalid quota interval {0} in quota policy {1}
FailedToResolveQuotaIntervalTimeUnitReference Failed to resolve quota time unit reference {0} in quota policy {1}
InvalidQuotaTimeUnit Invalid quota time unit {0} in quota policy {1}
InvalidTimeUnitForDistributedQuota Invalid timeunit {0} for distributed quota
InvalidSynchronizeIntervalForAsyncConfiguration 'SyncIntervalInSeconds' should be a value greater than zero
InvalidSynchronizeMessageCountForAsyncConfiguration 'SyncMessageCount' should be a value greater than zero
InvalidAsynchronizeConfigurationForSynchronousQuota AsynchronousConfiguration is not valid for synchronous quota
InvalidQuotaType Invalid Quotatype:{0};Valid Types are calendar,rollingwindow,flexi
InvalidStartTime Invalid Starttime:{0}; Start Time should be of the format 'yyyy-MM-dd HH:mm:ss
StartTimeNotSupported Starttime is not supported for quotatype {0}. Starttime is supported only for 'calendar' based type

The current HTTP status code for exceeding the rate limit is 500, but it will soon be changed to 429. Until the change occurs, if you are want the status code to be 429, a property needs to be set on your organization (features.isHTTPStatusTooManyRequestEnabled). If you're a cloud customer, contact Apigee Support to have the property enabled.

If you're an Edge for Private Cloud customer, set this property with the following API call:

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

Schemas

See our GitHub repository samples for the most recent schemas.

Related topics

Reset Quota policy

Spike Arrest policy

Comparing Quota, Spike Arrest, and Concurrent Rate Limit Policies

Help or comments?