Limit Count Configuration
Configuration reference for the Limit Count plugin (`limit-count`): the parameters and plugin metadata, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) 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 (opens in Apache APISIX docs) and secrets (opens in Apache APISIX docs).
count — integer | string · optional · since APISIX 1.2 · API7 Gateway 3.1.0
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 (opens in Apache APISIX docs) 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 · since APISIX 1.2 · API7 Gateway 3.1.0
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 (opens in Apache APISIX docs) 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 · since APISIX 2.11.0 · API7 Gateway 3.1.0
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 · since APISIX 1.2 · API7 Gateway 3.1.0
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 (opens in Apache APISIX docs) 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 · since APISIX 1.2 · API7 Gateway 3.1.0
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 · since APISIX 2.9 · API7 Gateway 3.1.0
Valid values: any non-empty string
The response body returned when a request is rejected for exceeding the threshold.
policy — string · optional · default: local · since APISIX 1.2 · API7 Gateway 3.1.0
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 · since APISIX 3.18.0 · API7 Gateway 3.9.14
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 · since APISIX 3.18.0 · API7 Gateway 3.2.16.0
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 · since APISIX 2.9 · API7 Gateway 3.1.0
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 · since APISIX 2.9 · API7 Gateway 3.1.0
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 · since APISIX 2.12.0 · API7 Gateway 3.1.0
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 · since APISIX 1.2
The address of the Redis node. Required when policy is redis.
redis_port — integer · optional · default: 6379 · since APISIX 1.2
Valid values: greater than or equal to 1
The port of the Redis node when policy is redis.
redis_username — string · optional · since APISIX 3.9.0
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 · since APISIX 1.2
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 (opens in Apache APISIX docs) 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 · since APISIX 2.4
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 · since APISIX 3.9.0
If true, use SSL to connect to Redis when policy is redis.
redis_ssl_verify — boolean · optional · default: false · since APISIX 3.9.0
If true, verify the server SSL certificate when policy is redis.
redis_timeout — integer · optional · default: 1000 · since APISIX 1.2
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 · since APISIX 3.15.0
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 · since APISIX 3.15.0
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 · since APISIX 2.0
The list of Redis cluster nodes with at least one address. Required when policy is redis-cluster.
redis_cluster_name — string · optional · since APISIX 2.6
The name of the Redis cluster. Required when policy is redis-cluster.
redis_cluster_ssl — boolean · optional · default: false · since APISIX 3.9.0
If true, use SSL to connect to Redis cluster when policy is redis-cluster.
redis_cluster_ssl_verify — boolean · optional · default: false · since APISIX 3.9.0
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 (opens in Apache APISIX docs) 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 · since APISIX 3.12.0 · API7 Gateway 3.3.0
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 · since APISIX 3.16.0 · API7 Gateway 3.9.14
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 (opens in Apache APISIX docs) 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 · since APISIX 3.16.0 · API7 Gateway 3.9.14
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 (opens in Apache APISIX docs) 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 · since APISIX 3.16.0 · API7 Gateway 3.9.14
A variable expression that resolves to the key used to count requests for this rule. Prefix every APISIX built-in variable (opens in Apache APISIX docs) 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 · since APISIX 3.16.0 · API7 Gateway 3.9.14
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 · since APISIX 3.12.0 · API7 Gateway 3.2.16.7
Default response header name for the total rate limit quota.
remaining_header — string · optional · default: X-RateLimit-Remaining · since APISIX 3.12.0 · API7 Gateway 3.2.16.7
Default response header name for the remaining rate limit quota.
reset_header — string · optional · default: X-RateLimit-Reset · since APISIX 3.12.0 · API7 Gateway 3.2.16.7
Default response header name for the number of seconds until the rate limit counter resets.