Limit Count Configuration

Parameters

See plugin common configurations for configuration options available to all plugins.

This plugin supports referencing parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin and secrets.

count — integer | string · optional

Valid values: greater than 0

The maximum number of requests allowed within a given time interval.

A string value can reference a built-in variable by prefixing the variable with a dollar sign ($). Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.16.0. Earlier versions accept only integer values.

Required with time_window when rules is not configured. Do not configure count or time_window together with rules.

A string value must resolve to a positive integer no greater than 9007199254740991. An invalid value returns 500 Internal Server Error unless allow_degradation is true. Introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.
time_window — integer | string · optional

Valid values: greater than 0

The time interval corresponding to the rate limiting count in seconds.

A string value can reference a built-in variable by prefixing the variable with a dollar sign ($). Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.16.0. Earlier versions accept only integer values.

Required with count when rules is not configured. Do not configure count or time_window together with rules.

A string value must resolve to a positive integer no greater than 9007199254740991. An invalid value returns 500 Internal Server Error unless allow_degradation is true. Introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.
key_type — string · optional · default: var

Valid values: var, var_combination, or constant

The type of key.

If the key_type is var, the key is interpreted as a variable.

If the key_type is var_combination, the key is interpreted as a combination of variables.

If the key_type is constant, the key is interpreted as a constant.
key — string · optional · default: remote_addr

The key to count requests by.

If the key_type is var, the key is interpreted as a variable. The variable does not need to be prefixed by a dollar sign ($). See built-in variables for available variables.

If the key_type is var_combination, the key is interpreted as a combination of variables. All variables should be prefixed by dollar signs ($). For example, to configure the key to use a combination of two request headers custom-a and custom-b, the key should be configured as $http_custom_a $http_custom_b.

If the key_type is constant, the key is interpreted as a constant value.
rejected_code — integer · optional · default: 503

Valid values: between 200 and 599 inclusive

The HTTP status code returned when a request is rejected for exceeding the threshold.
rejected_msg — string · optional

Valid values: any non-empty string

The response body returned when a request is rejected for exceeding the threshold.
policy — string · optional · default: local

Valid values: local, redis, redis-cluster, or redis-sentinel

The policy for the rate limiting counter. Required for API7 Enterprise and optional for APISIX.

When set to local, the counter is stored in memory locally. When set to redis, the counter is stored on a Redis instance. When set to redis-cluster, the counter is stored in a Redis cluster. When set to redis-sentinel, the counter is stored on Redis nodes managed by Redis Sentinel.

The redis-sentinel value adds high availability through Sentinel-managed failover. Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
window_type — string · optional · default: fixed

Valid values: fixed or sliding

The rate limiting window algorithm. When set to fixed, a fixed window algorithm is used, where each time window enforces the quota independently. When set to sliding, a sliding window algorithm is used, which smooths out bursts at window boundaries by weighting the previous window when calculating the current count.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
sync_interval — number · optional · default: -1

Valid values: -1 or greater than or equal to 0.1; must be smaller than a numeric top-level time_window

The interval in seconds at which the local counter is synchronized to the shared store (Redis). Only takes effect when policy is redis, redis-cluster, or redis-sentinel. A value of -1 disables delayed synchronization, so each request synchronizes directly. When enabled, the value should not be smaller than 0.1 and should be smaller than time_window. Enabling delayed synchronization reduces the number of round trips to the shared store at the cost of slightly looser enforcement.

At runtime, if the applicable time_window is less than or equal to sync_interval, the gateway falls back to direct synchronization for that request. This can occur with variable-resolved values or values inside rules, which are evaluated at request time.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
allow_degradation — boolean · optional · default: false

If true, continue handling requests without rate limiting when the counter backend fails or a variable-resolved count or time_window is invalid. If false, these failures return 500 Internal Server Error.
show_limit_quota_header — boolean · optional · default: true

If true, include quota headers on the response.

With the default names, X-RateLimit-Limit is the total quota, X-RateLimit-Remaining is how many requests remain in the window, and X-RateLimit-Reset is the number of seconds until the counter resets.

You can rename those headers with plugin metadata. When rules is configured, each rule inserts its header_prefix (or the rule index if omitted) before RateLimit- so Limit, Remaining, and Reset stay distinct per rule. See rules.header_prefix.
group — string · optional

Valid values: non-empty

The group ID for the plugin, such that routes of the same group can share the same rate limiting counter.
redis_host — string · optional

The address of the Redis node. Required when policy is redis.
redis_port — integer · optional · default: 6379

Valid values: greater than or equal to 1

The port of the Redis node when policy is redis.
redis_username — string · optional

The username for Redis if Redis ACL is used. If you use the legacy authentication method requirepass, configure only the redis_password. Used when policy is redis or redis-sentinel.
redis_password — string · optional

The password of the Redis node when policy is redis, redis-cluster, or redis-sentinel. The password is encrypted at rest in API7 Enterprise. In APISIX, enable data encryption to encrypt it before etcd storage. Encryption was introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.
redis_database — integer · optional · default: 0

Valid values: greater than or equal to 0

The database number in Redis when policy is redis or redis-sentinel.
redis_ssl — boolean · optional · default: false

If true, use SSL to connect to Redis when policy is redis.
redis_ssl_verify — boolean · optional · default: false

If true, verify the server SSL certificate when policy is redis.
redis_timeout — integer · optional · default: 1000

Valid values: greater than or equal to 1

The Redis timeout value in milliseconds when policy is redis or redis-cluster.
redis_keepalive_timeout — integer · optional

Valid values: greater than or equal to 1000 for redis and redis-cluster; greater than or equal to 1 for redis-sentinel

Keepalive timeout in milliseconds for Redis connections. When policy is redis or redis-cluster, the default is 10000 and the minimum is 1000. When policy is redis-sentinel, the default is 60000 and the minimum is 1.

Introduced in API7 Enterprise 3.9.16 and 3.10.3, and APISIX 3.15.0. Sentinel defaults were introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
redis_keepalive_pool — integer · optional · default: 100

Valid values: greater than or equal to 1

Keepalive pool size for Redis when policy is redis or redis-cluster.

Introduced in API7 Enterprise 3.9.16 and 3.10.3, and APISIX 3.15.0.
redis_cluster_nodes — array[string] · optional

The list of Redis cluster nodes with at least one address. Required when policy is redis-cluster.
redis_cluster_name — string · optional

The name of the Redis cluster. Required when policy is redis-cluster.
redis_cluster_ssl — boolean · optional · default: false

If true, use SSL to connect to Redis cluster when policy is redis-cluster.
redis_cluster_ssl_verify — boolean · optional · default: false

If true, verify the server SSL certificate when policy is redis-cluster.
redis_sentinels — array[object] · optional

The list of Redis Sentinel nodes, with at least one node. Required when policy is redis-sentinel. Each node is an object with host (string) and port (integer between 1 and 65535).

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
redis_master_name — string · optional

The name of the Redis master monitored by Sentinel. Required when policy is redis-sentinel.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
redis_role — string · optional · default: master

Valid values: master or slave

The role of the Redis node to connect to when policy is redis-sentinel. Use master for read and write operations, or slave for read-only replicas.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
redis_connect_timeout — integer · optional · default: 1000

Valid values: greater than or equal to 1

The connection timeout in milliseconds when policy is redis-sentinel.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
redis_read_timeout — integer · optional · default: 1000

Valid values: greater than or equal to 1

The read timeout in milliseconds when policy is redis-sentinel.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
sentinel_username — string · optional

The username used to authenticate with the Redis Sentinel nodes when policy is redis-sentinel.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.
sentinel_password — string · optional

The password used to authenticate with the Redis Sentinel nodes when policy is redis-sentinel.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.

The password is encrypted at rest in API7 Enterprise. In APISIX, enable data encryption to encrypt it before etcd storage. Encryption was introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.
rules — array[object] · optional

An array of rate-limiting rules that are applied sequentially. Do not configure rules together with the top-level count, time_window, or group fields. The top-level key and key_type are not used in rules mode. Rule keys must be unique. A rule whose key variable is absent from a request is skipped.

Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.16.0.
- count — integer | string · required
  
  Valid values: greater than 0
  
  The maximum number of requests allowed within the given time_window.
  
  This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).
  
  A string value must resolve to a positive integer no greater than 9007199254740991. If the rule applies and the value is invalid, the request returns 500 Internal Server Error unless allow_degradation is true. Introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.
- time_window — integer | string · required
  
  Valid values: greater than 0
  
  The time interval in seconds for the rate limiting count.
  
  This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).
  
  A string value must resolve to a positive integer no greater than 9007199254740991. If the rule applies and the value is invalid, the request returns 500 Internal Server Error unless allow_degradation is true. Introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.
- key — string · required
  
  A variable expression that resolves to the key used to count requests for this rule. Prefix every APISIX built-in variable or NGINX variable with a dollar sign ($), for example $remote_addr or $remote_addr $http_x_tenant.
  
  The top-level key_type does not apply to rules. A rule with no resolvable variable is skipped for that request.
- header_prefix — string · optional
  
  A prefix inserted before RateLimit- in this rule's quota headers so each rule stays distinguishable. With the default names, foo produces X-foo-RateLimit-Limit, X-foo-RateLimit-Remaining, and X-foo-RateLimit-Reset. Those headers still mean total quota, remaining quota, and seconds until reset. If omitted, the rule's array index is used, so the first rule becomes X-1-RateLimit-Limit. Only sent when show_limit_quota_header is true.

Plugin Metadata

limit_header — string · optional · default: X-RateLimit-Limit

Default response header name for the total rate limit quota.
remaining_header — string · optional · default: X-RateLimit-Remaining

Default response header name for the remaining rate limit quota.
reset_header — string · optional · default: X-RateLimit-Reset

Default response header name for the number of seconds until the rate limit counter resets.