Rate limit (proto)

This extension has the qualified name envoy.filters.http.ratelimit


This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.


This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

Rate limit configuration overview.


[extensions.filters.http.ratelimit.v3.RateLimit proto]

  "domain": ...,
  "stage": ...,
  "request_type": ...,
  "timeout": {...},
  "failure_mode_deny": ...,
  "rate_limited_as_resource_exhausted": ...,
  "rate_limit_service": {...},
  "enable_x_ratelimit_headers": ...,
  "disable_x_envoy_ratelimited_header": ...,
  "rate_limited_status": {...},
  "response_headers_to_add": [],
  "status_on_error": {...},
  "stat_prefix": ...

(string, REQUIRED) The rate limit domain to use when calling the rate limit service.


(uint32) Specifies the rate limit configurations to be applied with the same stage number. If not set, the default stage number is 0.


The filter supports a range of 0 - 10 inclusively for stage numbers.


(string) The type of requests the filter should apply to. The supported types are internal, external or both. A request is considered internal if x-envoy-internal is set to true. If x-envoy-internal is not set or false, a request is considered external. The filter defaults to both, and it will apply to all request types.


(Duration) The timeout in milliseconds for the rate limit service RPC. If not set, this defaults to 20ms.


(bool) The filter’s behaviour in case the rate limiting service does not respond back. When it is set to true, Envoy will not allow traffic in case of communication failure between rate limiting service and the proxy.


(bool) Specifies whether a RESOURCE_EXHAUSTED gRPC code must be returned instead of the default UNAVAILABLE gRPC code for a rate limited gRPC call. The HTTP code will be 200 for a gRPC response.


(config.ratelimit.v3.RateLimitServiceConfig, REQUIRED) Configuration for an external rate limit service provider. If not specified, any calls to the rate limit service will immediately return success.


(extensions.filters.http.ratelimit.v3.RateLimit.XRateLimitHeadersRFCVersion) Defines the standard version to use for X-RateLimit headers emitted by the filter:

  • X-RateLimit-Limit - indicates the request-quota associated to the client in the current time-window followed by the description of the quota policy. The values are returned by the rate limiting service in current_limit field. Example: 10, 10;w=1;name="per-ip", 1000;w=3600.

  • X-RateLimit-Remaining - indicates the remaining requests in the current time-window. The values are returned by the rate limiting service in limit_remaining field.

  • X-RateLimit-Reset - indicates the number of seconds until reset of the current time-window. The values are returned by the rate limiting service in duration_until_reset field.

In case rate limiting policy specifies more then one time window, the values above represent the window that is closest to reaching its limit.

For more information about the headers specification see selected version of the draft RFC.

Disabled by default.


(bool) Disables emitting the x-envoy-ratelimited header in case of rate limiting (i.e. 429 responses). Having this header not present potentially makes the request retriable.


(type.v3.HttpStatus) This field allows for a custom HTTP response status code to the downstream client when the request has been rate limited. Defaults to 429 (TooManyRequests).


If this is set to < 400, 429 will be used instead.


(repeated config.core.v3.HeaderValueOption) Specifies a list of HTTP headers that should be added to each response for requests that have been rate limited.


(type.v3.HttpStatus) Sets the HTTP status that is returned to the client when the ratelimit server returns an error or cannot be reached. The default status is 500.


(string) Optional additional prefix to use when emitting statistics. This allows to distinguish emitted statistics between configured ratelimit filters in an HTTP filter chain.

Enum extensions.filters.http.ratelimit.v3.RateLimit.XRateLimitHeadersRFCVersion

[extensions.filters.http.ratelimit.v3.RateLimit.XRateLimitHeadersRFCVersion proto]

Defines the version of the standard to use for X-RateLimit headers.


(DEFAULT) ⁣X-RateLimit headers disabled.


⁣Use draft RFC Version 03.


[extensions.filters.http.ratelimit.v3.RateLimitPerRoute proto]

  "vh_rate_limits": ...,
  "domain": ...

(extensions.filters.http.ratelimit.v3.RateLimitPerRoute.VhRateLimitsOptions) Specifies if the rate limit filter should include the virtual host rate limits.


(string) Overrides the domain. If not set, uses the filter-level domain instead.

Enum extensions.filters.http.ratelimit.v3.RateLimitPerRoute.VhRateLimitsOptions

[extensions.filters.http.ratelimit.v3.RateLimitPerRoute.VhRateLimitsOptions proto]


(DEFAULT) ⁣Use the virtual host rate limits unless the route has a rate limit policy.


⁣Use the virtual host rate limits even if the route has a rate limit policy.


⁣Ignore the virtual host rate limits even if the route does not have a rate limit policy.