Limit Count | APISIX & API7 API Gateway Docs

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
vaild vaule:
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
vaild vaule:
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
default: var
vaild vaule:
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
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
default: 503
vaild vaule:
between 200 and 599 inclusive
The HTTP status code returned when a request is rejected for exceeding the threshold.
rejected_msg
string
vaild vaule:
any non-empty string
The response body returned when a request is rejected for exceeding the threshold.
policy
string
default: local
vaild vaule:
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
default: fixed
vaild vaule:
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
default: -1
vaild vaule:
-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
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
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
vaild vaule:
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
The address of the Redis node. Required when policy is redis.
redis_port
integer
default: 6379
vaild vaule:
greater than or equal to 1
The port of the Redis node when policy is redis.
redis_username
string
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
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
default: 0
vaild vaule:
greater than or equal to 0
The database number in Redis when policy is redis or redis-sentinel.
redis_ssl
boolean
default: false
If true, use SSL to connect to Redis when policy is redis.
redis_ssl_verify
boolean
default: false
If true, verify the server SSL certificate when policy is redis.
redis_timeout
integer
default: 1000
vaild vaule:
greater than or equal to 1
The Redis timeout value in milliseconds when policy is redis or redis-cluster.
redis_keepalive_timeout
integer
vaild vaule:
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
default: 100
vaild vaule:
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]
The list of Redis cluster nodes with at least one address. Required when policy is redis-cluster.
redis_cluster_name
string
The name of the Redis cluster. Required when policy is redis-cluster.
redis_cluster_ssl
boolean
default: false
If true, use SSL to connect to Redis cluster when policy is redis-cluster.
redis_cluster_ssl_verify
boolean
default: false
If true, verify the server SSL certificate when policy is redis-cluster.
redis_sentinels
array[object]
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
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
default: master
vaild vaule:
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
default: 1000
vaild vaule:
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
default: 1000
vaild vaule:
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
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
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]
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
  vaild vaule:
  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
  vaild vaule:
  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
  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
default: X-RateLimit-Limit
Default response header name for the total rate limit quota.
remaining_header
string
default: X-RateLimit-Remaining
Default response header name for the remaining rate limit quota.
reset_header
string
default: X-RateLimit-Reset
Default response header name for the number of seconds until the rate limit counter resets.

Parameters​

Plugin Metadata​

Parameters

Plugin Metadata