Configuration#

Using Flask Config#

The following Flask Configuration values are honored by Limiter. If the corresponding configuration value is also present as an argument to the Limiter constructor, the constructor argument will take priority.

RATELIMIT_ENABLED#

Constructor argument: enabled

Overall kill switch for rate limits. Defaults to True

RATELIMIT_KEY_FUNC#

Constructor argument: key_func

A callable that returns the domain to rate limit (e.g. username, ip address etc)

RATELIMIT_KEY_PREFIX#

Constructor argument: key_prefix

Prefix that is prepended to each stored rate limit key and app context global name. This can be useful when using a shared storage for multiple applications or rate limit domains. For multi-instance use cases, explicitly pass key_prefix keyword argument to Limiter constructor instead.

RATELIMIT_APPLICATION#

Constructor argument: application_limits

A comma (or some other delimiter) separated string that will be used to apply limits to the application as a whole (i.e. shared by all routes).

RATELIMIT_APPLICATION_COST#

Constructor argument: application_limits_cost

The cost of a hit to the application wide shared limit as an integer or a function that takes no parameters and returns the cost as an integer (Default: 1)

RATELIMIT_DEFAULT#

Constructor argument: default_limits

A comma (or some other delimiter) separated string that will be used to apply a default limit on all routes. If not provided, the default limits can be passed to the Limiter constructor as well (the values passed to the constructor take precedence over those in the config). Rate limit string notation for details.

RATELIMIT_DEFAULTS_PER_METHOD#

Constructor argument: default_limits_per_method

Whether default limits are applied per method, per route or as a combination of all method per route.

RATELIMIT_DEFAULTS_COST#

Constructor argument: default_limits_cost

The cost of a hit to the default limits as an integer or a function that takes no parameters and returns the cost as an integer (Default: 1)

RATELIMIT_DEFAULTS_EXEMPT_WHEN#

Constructor argument: default_limits_exempt_when

A function that should return a truthy value if the default rate limit(s) should be skipped for the current request. This callback is called from the flask request context before_request() hook.

RATELIMIT_DEFAULTS_DEDUCT_WHEN#

Constructor argument: default_limits_deduct_when

A function that should return a truthy value if a deduction should be made from the default rate limit(s) for the current request. This callback is called from the flask request context after_request() hook.

RATELIMIT_STORAGE_URI#

Constructor argument: storage_uri

A storage location conforming to the scheme in Supported versions. A basic in-memory storage can be used by specifying memory:// but it should be used with caution in any production setup since:

  1. Each application process will have it’s own storage

  2. The state of the rate limits will not persist beyond the process’ life-time.

Other supported backends include:

  • Memcached: memcached://host:port

  • MongoDB: mongodb://host:port

  • Redis: redis://host:port

For specific examples and requirements of supported backends please refer to Supported versions and the limits library.

RATELIMIT_STORAGE_OPTIONS#

Constructor argument: storage_options

A dictionary to set extra options to be passed to the storage implementation upon initialization.

RATELIMIT_STRATEGY#

Constructor argument: strategy

The rate limiting strategy to use. Rate limiting strategies for details.

RATELIMIT_HEADERS_ENABLED#

Constructor argument: headers_enabled

Enables returning Rate-limiting Headers. Defaults to False

RATELIMIT_HEADER_LIMIT#

Constructor argument: header_name_mapping

Header for the current rate limit. Defaults to X-RateLimit-Limit

RATELIMIT_HEADER_RESET#

Constructor argument: header_name_mapping

Header for the reset time of the current rate limit. Defaults to X-RateLimit-Reset

RATELIMIT_HEADER_REMAINING#

Constructor argument: header_name_mapping

Header for the number of requests remaining in the current rate limit. Defaults to X-RateLimit-Remaining

RATELIMIT_HEADER_RETRY_AFTER#

Constructor argument: header_name_mapping

Header for when the client should retry the request. Defaults to Retry-After

RATELIMIT_HEADER_RETRY_AFTER_VALUE#

Constructor argument: retry_after

Allows configuration of how the value of the Retry-After header is rendered. One of http-date or delta-seconds. (RFC2616).

RATELIMIT_SWALLOW_ERRORS#

Constructor argument: swallow_errors

Whether to allow failures while attempting to perform a rate limit such as errors with downstream storage. Setting this value to True will effectively disable rate limiting for requests where an error has occurred.

RATELIMIT_IN_MEMORY_FALLBACK_ENABLED#

Constructor argument: in_memory_fallback_enabled

True/False. If enabled an in memory rate limiter will be used as a fallback when the configured storage is down. Note that, when used in combination with RATELIMIT_IN_MEMORY_FALLBACK the original rate limits will not be inherited and the values provided in

RATELIMIT_IN_MEMORY_FALLBACK#

Constructor argument: in_memory_fallback

A comma (or some other delimiter) separated string that will be used when the configured storage is down.

RATELIMIT_FAIL_ON_FIRST_BREACH#

Constructor argument: fail_on_first_breach

Whether to stop processing remaining limits after the first breach. Default to True

RATELIMIT_ON_BREACH_CALLBACK#

Constructor argument: on_breach_callback

A function that will be called when any limit in this extension is breached.

Rate limit string notation#

Rate limits are specified as strings following the format:

[count] [per|/] [n (optional)] [second|minute|hour|day|month|year][s]

You can combine multiple rate limits by separating them with a delimiter of your choice.

Examples#

  • 10 per hour

  • 10 per 2 hours

  • 10/hour

  • 5/2 seconds;10/hour;100/day;2000 per year

  • 100/day, 500/7 days

Warning

If rate limit strings that are provided to the limit() decorator are malformed and can’t be parsed the decorated route will fall back to the default rate limit(s) and an ERROR log message will be emitted. Refer to Logging for more details on capturing this information. Malformed default rate limit strings will however raise an exception as they are evaluated early enough to not cause disruption to a running application.

Rate-limiting Headers#

If the configuration is enabled, information about the rate limit with respect to the route being requested will be added to the response headers. Since multiple rate limits can be active for a given route - the rate limit with the lowest time granularity will be used in the scenario when the request does not breach any rate limits.

X-RateLimit-Limit

The total number of requests allowed for the active window

X-RateLimit-Remaining

The number of requests remaining in the active window.

X-RateLimit-Reset

UTC seconds since epoch when the window will be reset.

Retry-After

Seconds to retry after or the http date when the Rate Limit will be reset. The way the value is presented depends on the configuration value set in RATELIMIT_HEADER_RETRY_AFTER_VALUE and defaults to delta-seconds.

The header names can be customised if required by either using the flask configuration ( RATELIMIT_HEADER_LIMIT, RATELIMIT_HEADER_RESET, RATELIMIT_HEADER_RETRY_AFTER, RATELIMIT_HEADER_REMAINING ) values or by providing the header_name_mapping argument to the extension constructor as follows:

from flask_limiter import Limiter, HEADERS
limiter = Limiter(header_name_mapping={
     HEADERS.LIMIT : "X-My-Limit",
     HEADERS.RESET : "X-My-Reset",
     HEADERS.REMAINING: "X-My-Remaining"
  }
)