Skip to main content
API7.ai Logo

Parameters​

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

Stream Route Parameters​

  • conn

    integer

    required

    vaild vaule:

    greater than 0

    The number of concurrent stream connections allowed for each resolved key without delay.

  • burst

    integer

    required

    vaild vaule:

    greater than or equal to 0

    The number of additional concurrent connections allowed to wait. Connections above conn + burst are rejected by closing the stream.

  • default_conn_delay

    number

    required

    vaild vaule:

    greater than 0

    The base delay in seconds for connections above conn and at or below conn + burst. The calculated delay is default_conn_delay × floor((current connections - 1) / conn). Delays below 0.001 seconds are not applied.

  • only_use_default_delay

    boolean

    default: false

    On stream routes, connection latency does not update the delay, so this setting does not change stream behavior.

  • key_type

    string

    default: var

    vaild vaule:

    var or var_combination

    Whether key names one stream variable (var) or combines multiple stream variables (var_combination).

  • key

    string

    required

    The key used to group connection counters.

    With key_type: var, omit the dollar sign, for example remote_addr. If the variable has no value, APISIX falls back to remote_addr.

    With key_type: var_combination, prefix each variable with a dollar sign, for example $remote_addr $server_addr.

HTTP Route Parameters​

note

For HTTP routes 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

    vaild vaule:

    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.

    Required with burst and key when rules is not configured. Do not configure these top-level fields together with rules.

  • burst

    integer | string

    vaild vaule:

    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.

    Required with conn and key when rules is not configured. Do not configure these top-level fields together with rules.

  • default_conn_delay

    number

    required

    vaild vaule:

    greater than 0

    The base delay in seconds for requests above conn and at or below conn + burst. The calculated delay is default_conn_delay × floor((current concurrent requests - 1) / conn). Delays below 0.001 seconds are not applied.

  • only_use_default_delay

    boolean

    default: false

    If true, omit request-latency feedback when a request completes. If false, pass the observed latency to the limiter.

    In APISIX 3.19.0 and API7 Gateway 3.9.21 and 3.10.8, neither value changes the delay applied to later requests. Each request uses default_conn_delay as its delay unit.

    Requests above conn + burst are rejected immediately regardless of this setting.

  • key_type

    string

    default: var

    vaild vaule:

    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

    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.

    Required with conn and burst when rules is not configured. Do not configure these top-level fields together with rules.

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

  • allow_degradation

    boolean

    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]

    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

      vaild vaule:

      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

      vaild vaule:

      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

      A variable expression that resolves to the key used to count requests for this rule. Prefix each variable with $; both $variable and ${variable} forms are accepted. For example, use ${http_custom_a} or ${http_custom_a}_${http_custom_b}.

      The top-level key_type does not apply to rules. A rule applies when at least one variable reference resolves to a request value or its ?? default. A missing variable without a default contributes an empty string but does not count as resolved, so a partial expression can still apply when another variable resolves. An expression with no resolved variables, including a value with no variable references, is skipped.

      If rules is configured and no rule applies to a request, the gateway returns HTTP 500 by default. Setting allow_degradation to true lets the request continue without connection limiting.

      In an ADC configuration, escape a gateway expression with a simple name, such as ${http_user}, as ${http_user}. ADC treats an unescaped ${NAME} containing only word characters as load-time environment interpolation; dotted gateway variable names pass through unchanged.

  • policy

    string

    default: local

    vaild vaule:

    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

    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.

  • redis_password

    string

    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

    default: 0

    vaild vaule:

    greater than or equal to 0

    The database number in Redis when policy is redis.

  • 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_server_name

    string

    TLS server name used for SNI and, when certificate verification is enabled, hostname verification. Applies when policy is redis and redis_ssl is true. Defaults to redis_host. If the selected value is an IP address, no server name is sent. To verify a DNS-named certificate when connecting by IP, set this field to the certificate's DNS name and enable redis_ssl_verify.

    Introduced in API7 Enterprise 3.9.21 and 3.10.8, and in APISIX 3.19.0. This field applies to the single-node Redis connector, not Redis Cluster or Sentinel.

  • 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

    default: 10000

    vaild vaule:

    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

    default: 100

    vaild vaule:

    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

    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]

    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.