windowMs
number
Time frame for which requests are checked/remembered. The time window for each
user starts at their first request. After it elapses, the user’s hit count is
reset to zero. A new time window is then started on their next request.
Also used in the Retry-After
header when the limit is reached.
This value cannot be set to a function. If multiple time windows are needed,
create multiple rate limiters.
init
function (including all legacy
stores - see the data stores page), you may need to
configure this value twice, once here and once on the store. In some cases the
units also differ (e.g. seconds vs milliseconds).60000
ms (= 1 minute).
limit
The maximum number of connections to allow during thenumber | function
Renamed in v7.x frommax
tolimit
. However,max
will still be supported for backwards-compatibility.
window
before rate
limiting the client.
Can be the limit itself as a number or a (sync/async) function that accepts the
Express req
and res
objects and then returns a number.
max
to zero will no longer disable the rate
limiter - instead, it will ‘block’ all requests to that endpoint.5
.
An example of using a function:
message
any
The response body to send back when a client is rate limited.
May be a string, JSON object, or any other value that Express’s
res.send method supports. It
can also be a (sync/async) function that accepts the Express request and
response objects and then returns a string
, JSON object, etc.
Defaults to 'Too many requests, please try again later.'
An example of sending a JSON object:
handler
for more advanced use-cases, such as using
res.render()
to send a
templated response.
statusCode
number
The HTTP status code to send back when a client is rate limited.
Defaults to 429
.
429
is defined in
section 4 of IETF’s
RFC 6585.handler
function
Express request handler that sends back a response when a client is
rate-limited.
By default, sends back the statusCode
and message
set via the options
,
similar to this:
legacyHeaders
Whether to send the legacy rate limit headers for the limit (boolean
Renamed in6.x
fromheaders
tolegacyHeaders
.
X-RateLimit-Limit
), current usage (X-RateLimit-Remaining
) and reset time
(if the store provides it) (X-RateLimit-Reset
) on all responses. If set to
true
, the middleware also sends the Retry-After
header on all blocked
requests.
Defaults to true
.
true
for backward compatibility, and it
is recommended to set it to false
and use standardHeaders
instead.standardHeaders
Whether to enable support for headers conforming to the RateLimit header fields for HTTP standardization draft adopted by the IETF. If set toboolean
|'draft-6'
|'draft-7'
|'draft-8'
Renamed in6.x
fromdraft_polli_ratelimit_headers
tostandardHeaders
.
draft-6
, separate RateLimit-Policy
RateLimit-Limit
,
RateLimit-Remaining
, and, if the store supports it, RateLimit-Reset
headers
are set on the response, in accordance with the
sixth draft
of the IETF rate limit header specification.
If set to draft-7
, a combined RateLimit
header is set containing limit,
remaining, and reset values, and a RateLimit-Policy
header is set, in
accordance with the
seventh draft
of the IETF rate limit header specification. windowMs
is used for the reset
value if the store does not provide a reset time.
If set to draft-8
, a combined RateLimit
header is set containing the
remaining and reset values, along with a RateLimit-Policy
header, is set for
each rate limiter defined, in accordance with the
eighth draft
of the IETF rate limit header specification. The value of windowMs
is used for
the reset parameter if the store does not provide a reset time.
Note that the
ninth draft
of the IETF rate limit header specification does not specify any changes in the
function or format of the headers. Set this option to draft-8
for the same.
draft-7
or draft-8
headers, make sure that you are using
Express v4.11
or later, as the implementation of these two drafts requires the
response.append
function.true
, it is treated as draft-6
, however, this behavior may change
in a future semver major release.
If set to any truthy value, the middleware also sends the Retry-After
header
on all blocked requests.
The standardHeaders
option may be used in conjunction with, or instead of the
legacyHeaders
option.
false
.
identifier
string | function
The name associated with the quota policy that this instance of the rate limiter
enforces. It is used in the RateLimit
and RateLimit-Policy
headers when
standardHeaders
is set to draft-8
, and ignored otherwise.
Can be the identifier itself as a string or a (sync/async) function that accepts
the Express req
and res
objects and then returns a string.
Defaults to a function that returns a string of the format
{limit}-in-{window}
, e.g., 7-in-1.5sec
.
store
Store
The Store
to use to store the hit count for each client.
By default, the
memory-store
is used.
See Data Stores for a list of avalliable stores and other
information.
passOnStoreError
false
and express-rate-limit will call the
express error handler
in the event of a store error. In other words, the default is to “fail closed”
and block all requests if the datastore becomes unavailable.
Set this to true
to “fail open” allow the request(s) through without rate
limiting. The error will be logged in this case.
keyGenerator
function
Method to retrieve custom identifiers for clients, such as their IP address,
username, or API Key.
Should be a (sync/async) function that accepts the Express request
and
response
objects and then returns a string.
By default, the client’s IP address is used with the
ipKeyGenerator
method to apply the configured
ipv6Subnet
to IPv6 addresses.
Custom keyGenerator
s that fall back to IP addresses should use the provided
ipKeyGenerator
method and a chosen subnet for IPv6
addresses (see ipv6Subnet discussion below.)
keyGenerator
returns the same value for every user, it becomes a global
rate limiter. This could be combined with a second instance of
express-rate-limit
to have both global and per-user limits.ipv6Subnet
IPv6 subnet mask applied to IPv6 addresses in the defaultnumber
(32-64) |function
|false
keyGenerator
.
Generally, ISPs that support IPv6 give each of their customers a range of IPv6
addresses via a subnet mask, whereas they usually provide only a single IPv4
address per customer. A malicious user could iterate through their range of IPv6
addresses and bypass simple IP-based rate limiting. This setting counteracts
that by allowing the rate-limiter to block an entire range of IPv6 addresses at
once.
It’s generally not possible to know what subnet an ISP has assigned to a user,
so we have to make an educuated guess.
The default value is 56, corresponding to a /56 subnet.
The valid range is 1-128, but typically ISPs assign subnets in the range of
32-64, with 64 being the most common. The validation check (which can be
disabled) will warn for values outside the 32-64 range.
Smaller values block larger ranges of IPs at once. 56 is a moderately aggressive
default. It may be increased to if users are being incorrectly blocked (try 60
or 64), or decreased if you are seeing evidence of abuse.
64, 60 (Comcast), 56, and 48
are all common values used by various ISPs.
The option may also be set to a function that returns the value if you want to
apply different subnets to different users. (It’s not always possible to know
what subnet a given user has, but you could make an educuated guess based on
their ISP - see the example below.)
Set to false to disable and always use the IP without masking.
This example uses the node.js built-in
net.BlockList
to apply
different subnets to different IP ranges:
requestPropertyName
string
The name of the property on the Express request
object to store the rate limit
info.
Defaults to 'rateLimit'
.
skip
function
Function to determine whether or not this request counts towards a client’s
quota. Should be a (sync/async) function that accepts the Express request
and
response
objects and then returns true
or false
.
Could also act as an allowlist for certain keys:
skipSuccessfulRequests
boolean
If true
, the library will (by default) skip all requests that are considered
‘failed’ by the requestWasSuccessful
function. By default, this means requests
succeed when the response status code less than 400
.
false
.
skipFailedRequests
boolean
When set to true
, failed requests won’t be counted. Request considered failed
when the requestWasSuccessful
option returns false
. By default, this means
requests fail when:
400
close
event triggered)error
event was triggered by responsefalse
.
requestWasSuccessful
function
Method to determine whether or not the request counts as ‘successful’. Used when
either skipSuccessfulRequests
or skipFailedRequests
is set to true. Should
be a (sync/async) function that accepts the Express req
and res
objects and
then returns true
or false
.
By default, requests with a response status code less than 400
are considered
successful:
validate
boolean | Object
When enabled, a set of validation checks are run at creation and on the first
request to detect common misconfigurations with proxies, etc. Prints an error to
the console if any issue is detected.
Automatically disables after the first request is processed.
If set to true
or false
, all validations are enabled or disabled.
If set to an object, individual validations can be enabled or disabled by name,
and the key default
controls all unspecified validations. For example:
true
.