Skip to content

rate-limit-by-key-policy.md

Latest commit

 

History

History
96 lines (73 loc) · 7.3 KB

rate-limit-by-key-policy.md

File metadata and controls

96 lines (73 loc) · 7.3 KB
title Azure API Management policy reference - rate-limit-by-key | Microsoft Docs
description Reference for the rate-limit-by-key policy available for use in Azure API Management. Provides policy usage, settings, and examples.
services api-management
author dlepow
ms.service azure-api-management
ms.topic reference
ms.date 11/14/2025
ms.author danlep

Limit call rate by key

[!INCLUDE api-management-availability-premium-dev-standard-basic-premiumv2-standardv2-basicv2]

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

[!INCLUDE api-management-rate-limit-accuracy]

[!INCLUDE api-management-policy-form-alert]

Policy statement

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

Attributes

Attribute Description Required Default
calls The maximum total number of calls allowed for the key value during the time interval specified in the renewal-period. Policy expressions are allowed. Yes N/A
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 (true). Policy expressions are allowed but will postpone evaluation and counter increment actions to end of outbound pipeline. No N/A
increment-count The number by which the counter is increased per request. Policy expressions are allowed but will postpone evaluation and counter increment to end of outbound pipeline. 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 calls. Maximum allowed value: 300 seconds. Policy expressions are 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 for the key value. Policy expressions aren't allowed. No Retry-After
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 for the key value. 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 key value in the time interval specified in the renewal-period. Policy expressions aren't allowed. No N/A
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 key value in 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

Usage

Usage notes

  • [!INCLUDE api-management-rate-limit-key-scope]
  • The v2 tiers use a token bucket algorithm for rate limiting, which differs from the sliding window algorithm in classic tiers. Because of this implementation difference, when you configure this policy in the v2 tiers at more than one scope and using the same counter-key value, ensure that the renewal-period and calls values are consistent in all instances of the policy. Inconsistent values can cause unpredictable behavior.
  • [!INCLUDE api-management-self-hosted-gateway-rate-limit] Learn more
  • [!INCLUDE api-management-rate-limit-gateway-calls]
  • When increment-condition or increment-count are defined using expressions, evaluation and increment of the rate limit counter are postponed to the end of outbound pipeline to allow for policy expressions based on the response. Limit exceeded condition is not evaluated at the same time in this case and will be evaluated on next incoming call. This leads to cases where 429 Too Many Requests status code is returned 1 call later than usual.

Example

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 for that caller IP address in the time period are stored in the variable remainingCallsPerIP.

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

Related policies

[!INCLUDE api-management-policy-ref-next-steps]