Limit call rate by key
rate-limit-by-key policy prevents API usage spikes on a per key basis by limiting the call rate to a specified number per a specified time period. The key can have an arbitrary string value and is typically provided using a policy expression. Optional increment condition can be added to specify which requests should be counted towards the limit. When this 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.
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.
Set the policy's elements and child elements in the order provided in the policy statement. To help you configure this policy, the portal provides a guided, form-based editor. Learn more about how to set or edit API Management policies.
<rate-limit-by-key calls="number" renewal-period="seconds" increment-condition="condition" increment-count="number" counter-key="key value" 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"/>
|calls||The maximum total number of calls allowed during the time interval specified in the
|counter-key||The key to use for the rate limit policy. For each key value, a single counter is used for all scopes at which the policy is configured. Policy expressions are allowed.||Yes||N/A|
|increment-condition||The Boolean expression specifying if the request should be counted towards the rate (
|increment-count||The number by which the counter is increased per request. Policy expressions are allowed.||No||1|
|renewal-period||The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in
|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-variable-name||The name of a policy expression 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
|remaining-calls-variable-name||The name of a policy expression variable that after each policy execution stores the number of remaining calls allowed for the time interval specified in the
|total-calls-header-name||The name of a response header whose value is the value specified in
- Policy sections: inbound
- Policy scopes: global, workspace, product, API, operation
- Gateways: dedicated, self-hosted
- 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
In the following example, the rate limit of 10 calls per 60 seconds is keyed by the caller IP address. After each policy execution, the remaining calls allowed in the time period are stored in the variable
<policies> <inbound> <base /> <rate-limit-by-key calls="10" renewal-period="60" increment-condition="@(context.Response.StatusCode == 200)" counter-key="@(context.Request.IpAddress)" remaining-calls-variable-name="remainingCallsPerIP"/> </inbound> <outbound> <base /> </outbound> </policies>
For more information and examples of this policy, see Advanced request throttling with Azure API Management.
For more information about working with policies, see: