Limit Conn Configuration

Parameters

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

In API7 Enterprise (from 3.8.17) and in APISIX (from 3.16.0), you should configure one of the following parameter sets, but not both:

conn, burst, default_conn_delay, key
rules, default_conn_delay

conn — integer | string · required

Valid values: greater than 0

The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below conn + burst will be delayed.

A string value can reference a built-in variable by prefixing the variable name with a dollar sign ($). A resolved string must be a positive integer no greater than 9007199254740991. If resolution fails or produces an invalid value, the gateway returns 500 Internal Server Error unless degradation is enabled.

String-value support was introduced in API7 Enterprise 3.8.17 and APISIX 3.16.0. The validation requirements were introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0. Earlier APISIX versions accept only integer values.
burst — integer | string · required

Valid values: greater than or equal to 0

The number of excessive concurrent requests allowed to be delayed. Requests exceeding conn + burst will be rejected immediately.

A string value can reference a built-in variable by prefixing the variable name with a dollar sign ($). A resolved string must be a non-negative integer no greater than 9007199254740991. If resolution fails or produces an invalid value, the gateway returns 500 Internal Server Error unless degradation is enabled.

String-value support was introduced in API7 Enterprise 3.8.17 and APISIX 3.16.0. The validation requirements were introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0. Earlier APISIX versions accept only integer values.
default_conn_delay — number · required

Valid values: greater than 0

Processing latency allowed in seconds for concurrent requests exceeding conn and up to conn + burst, which can be dynamically adjusted based on only_use_default_delay setting.
only_use_default_delay — boolean · optional · default: false

If false, delay requests proportionally based on how much they exceed the conn limit. The delay grows larger as congestion increases. For instance, with conn being 5, burst being 3, and default_conn_delay being 1, 6 concurrent requests would result in a 1-second delay, 7 requests a 2-second delay, 8 requests a 3-second delay, and so on, until the total limit of conn + burst is reached, beyond which requests are rejected.

If true, use default_conn_delay to delay all excessive requests within the burst range. Requests beyond conn + burst are rejected immediately. For instance, with conn being 5, burst being 3, and default_conn_delay being 1, 6, 7, or 8 concurrent requests are all delayed by exactly 1 second each.
key_type — string · optional · default: var

Valid values: var or var_combination

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.
key — string · required

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.
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.
allow_degradation — boolean · optional · default: false

If true, allow the gateway to continue handling requests without the plugin when the plugin or its dependencies become unavailable.
rules — array[object] · optional

An array of rate-limiting rules that are applied sequentially.

Rule support was introduced in API7 Enterprise 3.8.17 and APISIX 3.16.0.
- conn — integer | string · required
  
  Valid values: greater than 0
  
  The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below conn + burst will be delayed.
  
  A string value can reference a built-in variable by prefixing the variable name with a dollar sign ($). A resolved string must be a positive integer no greater than 9007199254740991.
  
  String-value validation was introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.
- burst — integer | string · required
  
  Valid values: greater than or equal to 0
  
  The number of excessive concurrent requests allowed to be delayed. Requests exceeding conn + burst will be rejected immediately.
  
  A string value can reference a built-in variable by prefixing the variable name with a dollar sign ($). A resolved string must be a non-negative integer no greater than 9007199254740991.
  
  String-value validation was introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.
- key — string · required
  
  The key to count requests by. If the configured key does not exist, the rule will not be executed.
  
  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.
policy — string · optional · default: local

Valid values: local, redis, or redis-cluster

The policy for rate limiting counter. Required for API7 Enterprise (from 3.9.0) 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.
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.
redis_password — string · optional

The password of the Redis node when policy is redis or redis-cluster. 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.
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 · default: 10000

Valid values: greater than or equal to 1000

Keepalive timeout in milliseconds for Redis when policy is redis or redis-cluster.

This parameter is available in API7 Enterprise from version 3.9.17 on the 3.9 line and from version 3.10.4 on the 3.10 line, and in APISIX from version 3.15.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.

This parameter is available in API7 Enterprise from version 3.9.17 on the 3.9 line and from version 3.10.4 on the 3.10 line, and in APISIX from version 3.15.0.
key_ttl — integer · optional · default: 3600

TTL of the Redis key in seconds when policy is redis or redis-cluster. Available in API7 Enterprise from version 3.9.4 and in APISIX from version 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.