Please note that if a Fastify version is out of support, then so are the corresponding versions of this plugin
in the table above.
See Fastify's LTS policy for more details.
Usage
Register the plugin and, if required, pass some custom options.
This plugin will add an onRequest hook to check if a client (based on their IP address) has made too many requests in the given timeWindow.
global : indicates if the plugin should apply rate limiting to all routes within the encapsulation scope.
max: maximum number of requests a single client can perform inside a timeWindow. It can be an async function with the signature async (request, key) => {} where request is the Fastify request object and key is the value generated by the keyGenerator. The function must return a number.
ban: maximum number of 429 responses to return to a client before returning 403 responses. When the ban limit is exceeded, the context argument that is passed to errorResponseBuilder will have its ban property set to true. Note:0 can also be passed to directly return 403 responses when a client exceeds the max limit.
timeWindow: the duration of the time window. It can be expressed in milliseconds, as a string (in the ms format), or as an async function with the signature async (request, key) => {} where request is the Fastify request object and key is the value generated by the keyGenerator. The function must return a number.
cache: this plugin internally uses an LRU cache to handle the clients, you can change the size of the cache with this option
allowList: array of string of IPs to exclude from rate limiting. It can be a sync or async function with the signature (request, key) => {} where request is the Fastify request object and key is the value generated by the keyGenerator. If the function return a truthy value, the request will be excluded from the rate limit.
redis: by default, this plugin uses an in-memory store, but if an application runs on multiple servers, an external store will be needed. This plugin requires the use of . the of an ioredis instance are not optimal for rate limiting. We recommend customizing the and parameters as shown in the .
keyGenerator example usage:
await fastify.register(import('@fastify/rate-limit'), { /* ... */ keyGenerator: function (request) { return request.headers['x-real-ip'] // nginx || request.headers['x-client-ip'] // apache || request.headers['x-forwarded-for'] // use this only if you trust the header || request.session.username // you can limit based on any session value || request.ip // fallback to default }})
Variable max example usage:
// In the same timeWindow, the max value can change based on request and/or key like thisfastify.register(rateLimit, { /* ... */ keyGenerator (request) { return request.headers['service-key'] }, max: async (request, key) => { return key === 'pro' ? 3 : 2 }, timeWindow: 1000})
errorResponseBuilder example usage:
await fastify.register(import('@fastify/rate-limit'), { /* ... */ errorResponseBuilder: function (request, context) { return { statusCode: 429, error: 'Too Many Requests', message: `I only allow ${context.max} requests per ${context.after} to this Website. Try again soon.`, date: Date.now(), expiresIn: context.ttl // milliseconds } }})
NOTE: The timeWindow will always be passed as the numeric value in milliseconds into the store's constructor.
function CustomStore (options) { this.options = options this.current = 0}CustomStore.prototype.incr = function (key, cb, timeWindow, max) { this.current++ cb(null, { current: this.current, ttl: timeWindow - (this.current * 1000) })}CustomStore.prototype.child = function (routeOptions) { // We create a merged copy of the current parent parameters with the specific // route parameters and pass them into the child store. const childParams = Object.assign(this.options, routeOptions) const store
The routeOptions object passed to the child method of the store will contain the same options that are detailed above for plugin registration with any specific overrides provided on the route. In addition, the following parameter is provided:
routeInfo: The configuration of the route including method, url, path, and the full route config
Custom onExceeding example usage:
await fastify.register(import('@fastify/rate-limit'), { /* */ onExceeding: function (req, key) { console.log('callback on exceeding ... executed before response to client') }})
Custom onExceeded example usage:
await fastify.register(import('@fastify/rate-limit'), { /* */ onExceeded: function (req, key) { console.log('callback on exceeded ... executed before response to client') }})
Custom onBanReach example usage:
await fastify.register(import('@fastify/rate-limit'), { /* */ ban: 10, onBanReach: function (req, key) { console.log('callback on exceeded ban limit') }})
Options on the endpoint itself
Rate limiting can also be configured at the route level, applying the configuration independently.
For example the allowList if configured:
on plugin registration will affect all endpoints within the encapsulation scope
on route declaration will affect only the targeted endpoint
The global allowlist is configured when registering it with fastify.register(...).
The endpoint allowlist is set on the endpoint directly with the { config : { rateLimit : { allowList : [] } } } object.
ACL checking is performed based on the value of the key from the keyGenerator.
In this example, we are checking the IP address, but it could be an allowlist of specific user identifiers (like JWT or tokens):
import Fastify from 'fastify'const fastify = Fastify()await fastify.register(import('@fastify/rate-limit'), { global : false, // don't apply these settings to all the routes of the context max: 3000, // default global max rate limit allowList: ['192.168.0.10'], // global allowlist access. redis: redis, // custom connection to redis })// add a limited route with this configuration plus the global onefastify.get('/', { config: { rateLimit: { max: 3, timeWindow: '1 minute' }
In the route creation you can override the same settings of the plugin registration plus the following additional options:
onExceeding : callback that will be executed each time a request is made to a route that is rate-limited
onExceeded : callback that will be executed when a user reaches the maximum number of tries. Can be useful to blacklist clients
You may also want to set a global rate limiter and then disable it on some routes:
import Fastify from 'fastify'const fastify = Fastify()await fastify.register(import('@fastify/rate-limit'), { max: 100, timeWindow: '1 minute'})// add a limited route with global configfastify.get('/', (request, reply) => { reply.send({ hello: 'from ... rate limited root' })})// this route doesn't have any rate limitfastify.get('/public', { config: { rateLimit: false }}, (request, reply) => {
Manual Rate Limit
A custom limiter function can be created with fastify.createRateLimit(), which is handy when needing to integrate with
technologies like GraphQL or tRPC. This function uses the global options set
during plugin registration, but you can override options such as store, skipOnError, max, timeWindow,
allowList, keyGenerator, ipv6Subnet, and ban.
Example usage:
import Fastify from 'fastify'const fastify = Fastify()// register with global optionsawait fastify.register(import('@fastify/rate-limit'), { global : false, max: 100, timeWindow: '1 minute'})// checkRateLimit will use the global options provided above when calledconst checkRateLimit = fastify.createRateLimit();fastify.get("/", async (request, reply) => { // manually check the rate limit (using global options) const limit = await checkRateLimit(request);
A custom limiter function created with fastify.createRateLimit() only requires a FastifyRequest as the first parameter:
The returned limit is an object containing the following properties for the request passed to checkRateLimit.
isAllowed: if true, the request was excluded from rate limiting according to the configured allowList.
key: the generated key as returned by the keyGenerator function.
If isAllowed is false the object also contains these additional properties:
max: the configured max option as a number. If a max function was supplied as global option or to fastify.createRateLimit(), this property will correspond to the function's return type for the given request.
timeWindow: the configured timeWindow option in milliseconds. If a function was supplied to timeWindow, similar to the max property above, this property will be equal to the function's return type.
remaining: the remaining amount of requests before the limit is exceeded.
ttl: the remaining time until the limit will be reset in milliseconds.
ttlInSeconds: ttl in seconds.
isExceeded: true if the limit was exceeded.
isBanned: true if the request was banned according to the ban option.
The limiter function accepts an optional second argument { increment?: boolean }. The increment flag defaults to true, so omitting the argument keeps the original behavior (the request is consumed). When increment is false, the current rate limit status is returned without consuming a request. This is useful when a limit should only be enforced on certain outcomes (e.g. failed login attempts) while still checking the status before processing.
const checkRateLimit = fastify.createRateLimit({ max: 5, timeWindow: '1 minute' });fastify.post('/login', async (request, reply) => { // Peek at the current status without consuming a request const status = await checkRateLimit(request, { increment: false }); if (status.isExceeded) { return reply.code(429).send({ error: 'Too many attempts' }); } const success = await tryLogin(request.body); if (!success) { // Only consume a request when the login fails await checkRateLimit
A few things to keep in mind when using { increment: false }:
It is a non-mutating snapshot. A peek never increments the counter, resets the window, or advances the ban/continueExceeding/exponentialBackoff side effects that a real request triggers. The returned isExceeded/isBanned therefore reflect the current counters, but a peek will not, by itself, escalate a ban or extend a backoff window.
ttl reflects the store's current window. With the Redis store, ttl is the raw server PTTL (the same value incr reports), so it can exceed the configured timeWindow when continueExceeding/exponentialBackoff has extended it.
Custom stores must implement read. The flag relies on a non-mutating read(ip, cb, timeWindow, max) method, which mirrors the incr signature. The built-in local and Redis stores provide it; a custom store that does not will throw a clear error when called with { increment: false }.
Examples of Custom Store
These examples show an overview of the store feature and you should take inspiration from it and tweak as you need:
nameSpace: choose which prefix to use in the redis, default is 'fastify-rate-limit-'
continueExceeding: Renew user limitation when user sends a request to the server when still limited. This will take priority over exponentialBackoff
store: a custom store to track requests and rates which allows you to use your own storage mechanism (using an RDBMS, MongoDB, etc.) as well as further customizing the logic used in calculating the rate limits. A simple example is provided below as well as a more detailed example using Knex.js can be found in the example/ folder
skipOnError: if true it will skip errors generated by the storage (e.g. redis not reachable).
keyGenerator: a sync or async function to generate a unique identifier for each incoming request. Defaults to (request) => normalizeIP(request.ip, ipv6Subnet), the IP is resolved by fastify using request.connection.remoteAddress or request.headers['x-forwarded-for'] if trustProxy option is enabled. The default normalizes IP strings, maps IPv4-mapped IPv6 addresses to IPv4, and masks IPv6 addresses to the configured ipv6Subnet. Use it if you want to override this behavior
ipv6Subnet: the IPv6 prefix length used by the default keyGenerator. Defaults to 64. Set it to another prefix length when your clients commonly receive a different IPv6 allocation size. The normalizeIP(ip, ipv6Subnet) helper is also exported for custom key generators.
groupId: a string to group multiple routes together introducing separate per-group rate limit. This will be added on top of the result of keyGenerator.
errorResponseBuilder: a function to generate a custom response object. Defaults to (request, context) => ({statusCode: 429, error: 'Too Many Requests', message: ``Rate limit exceeded, retry in ${context.after}``})
addHeadersOnExceeding: define which headers should be added in the response when the limit is not reached. Defaults all the headers will be shown
addHeaders: define which headers should be added in the response when the limit is reached. Defaults all the headers will be shown
enableDraftSpec: if true it will change the HTTP rate limit headers following the IEFT draft document. More information at draft-ietf-httpapi-ratelimit-headers.md.
onExceeding: callback that will be executed before request limit has been reached.
onExceeded: callback that will be executed after request limit has been reached.
onBanReach: callback that will be executed when the ban limit has been reached.
exponentialBackoff: Renew user limitation exponentially when user sends a request to the server when still limited.
=
new
CustomStore
(childParams)
// Here is where you may want to do some custom calls on the store with the information