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_PER_METHOD Constructor argument: application_limits_per_method	Whether application limits are applied per method, per route or as a combination of all method per route.
RATELIMIT_APPLICATION_EXEMPT_WHEN Constructor argument: application_limits_exempt_when	A function that should return a truthy value if the application rate limit(s) should be skipped for the current request. This callback is called from the flask request context before_request() hook.
RATELIMIT_APPLICATION_DEDUCT_WHEN Constructor argument: application_limits_deduct_when	A function that should return a truthy value if a deduction should be made from the application rate limit(s) for the current request. This callback is called from the flask request context after_request() hook.
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 that are otherwise not decorated with an explicit rate limit. 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 Storage scheme. A basic in-memory storage can be used by specifying memory:// but it should be used with caution in any production setup since: Each application process will have it’s own storage 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 Storage scheme 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_REQUEST_IDENTIFIER Constructor argument: request_identifier	A callable that returns the unique identity of the current request. Defaults to flask.Request.endpoint
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.
RATELIMIT_META Constructor argument: meta_limits	A comma (or some other delimiter) separated string that will be used to control the upper limit of a requesting client hitting any configured rate limit. Once a meta limit is exceeded all subsequent requests will raise a RateLimitExceeded for the duration of the meta limit window.
RATELIMIT_ON_META_BREACH_CALLBACK Constructor argument: on_meta_breach_callback	A function that will be called when a meta 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"
  }
)