Limit call rate by subscription

  • Article

APPLIES TO: All API Management tiers

The rate-limit policy prevents API usage spikes on a per subscription basis by limiting the call rate to a specified number per a specified time period. When the call rate is exceeded, the caller receives a 429 Too Many Requests response status code.

To understand the difference between rate limits and quotas, see Rate limits and quotas.

Caution

Due to the distributed nature of throttling architecture, rate limiting is never completely accurate. The difference between the configured and the actual number of allowed requests varies based on request volume and rate, backend latency, and other factors.

Note

Set a policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

<rate-limit calls="number" renewal-period="seconds"  retry-after-header-name="custom header name, replaces default 'Retry-After'" 
        retry-after-variable-name="policy expression variable name"
        remaining-calls-header-name="header name"  
        remaining-calls-variable-name="policy expression variable name"
        total-calls-header-name="header name">
    <api name="API name" id="API id" calls="number" renewal-period="seconds" >
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" />
    </api>
</rate-limit>

Attributes

Attribute Description Required Default
calls The maximum total number of calls allowed during the time interval specified in renewal-period. Policy expressions aren't allowed. Yes N/A
renewal-period The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in calls. Maximum allowed value: 300 seconds. Policy expressions aren't allowed. Yes N/A
retry-after-header-name The name of a custom response header whose value is the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. No Retry-After
retry-after-variable-name The name of a variable that stores the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. No N/A
remaining-calls-header-name The name of a response header whose value after each policy execution is the number of remaining calls allowed for the time interval specified in the renewal-period. Policy expressions aren't allowed. No N/A
remaining-calls-variable-name The name of a variable that after each policy execution stores the number of remaining calls allowed for the time interval specified in the renewal-period. Policy expressions aren't allowed. No N/A
total-calls-header-name The name of a response header whose value is the value specified in calls. Policy expressions aren't allowed. No N/A

Elements

Element Description Required
api Add one or more of these elements to impose a call rate limit on APIs within the product. Product and API call rate limits are applied independently. API can be referenced either via name or id. If both attributes are provided, id will be used and name will be ignored. No
operation Add one or more of these elements to impose a call rate limit on operations within an API. Product, API, and operation call rate limits are applied independently. Operation can be referenced either via name or id. If both attributes are provided, id will be used and name will be ignored. No

api attributes

Attribute Description Required Default
name The name of the API for which to apply the rate limit. Either name or id must be specified. N/A
id The ID of the API for which to apply the rate limit. Either name or id must be specified. N/A
calls The maximum total number of calls allowed during the time interval specified in renewal-period. Policy expressions aren't allowed. Yes N/A
renewal-period The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in calls. Maximum allowed value: 300 seconds. Policy expressions aren't allowed. Yes N/A

operation attributes

Attribute Description Required Default
name The name of the operation for which to apply the rate limit. Either name or id must be specified. N/A
id The ID of the operation for which to apply the rate limit. Either name or id must be specified. N/A
calls The maximum total number of calls allowed during the time interval specified in renewal-period. Policy expressions aren't allowed. Yes N/A
renewal-period The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in calls. Maximum allowed value: 300 seconds. Policy expressions aren't allowed. Yes N/A

Usage

Usage notes

  • This policy can be used only once per policy definition.
  • This policy is only applied when an API is accessed using a subscription key.
  • Rate limit counts in a self-hosted gateway can be configured to synchronize locally (among gateway instances across cluster nodes), for example, through Helm chart deployment for Kubernetes or using the Azure portal deployment templates. However, rate limit counts don't synchronize with other gateway resources configured in the API Management instance, including the managed gateway in the cloud. Learn more

Example

In the following example, the per subscription rate limit is 20 calls per 90 seconds. After each policy execution, the remaining calls allowed in the time period are stored in the variable remainingCallsPerSubscription.

<policies>
    <inbound>
        <base />
        <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Next steps

For more information about working with policies, see: