ratelimit middleware for express
Last updated 5 years ago by defunctzombie .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install ratelimit-middleware 
SYNC missed versions from official npm registry.

ratelimit-middleware Build Status

Rate limit middleware for expressjs

var ratelimit = require('ratelimit-middleware');
var app = express();

    burst: 10,  // Max 10 concurrent requests (if tokens)
    rate: 0.5  // Steady state: 1 request / 2 seconds

app.get('/throttled/access', function(req, res, next) {


Creates an API rate limiter that can be plugged into the standard restify request handling pipeline.

This throttle gives you three options on which to throttle: username, IP address and 'X-Forwarded-For'. IP/XFF is a /32 match, so keep that in mind if using it. Username takes the user specified on req.username (which gets automagically set for supported Authorization types; otherwise set it yourself with a filter that runs before this).

In both cases, you can set a burst and a rate (in requests/seconds), as an integer/float. Those really translate to the TokenBucket algorithm, so read up on that (or see the comments above...).

In either case, the top level options burst/rate set a blanket throttling rate, and then you can pass in an overrides object with rates for specific users/IPs. You should use overrides sparingly, as we make a new TokenBucket to track each.


Name Default Type Description
rate - Number Steady state number of requests/second to allow
burst - Number Amount of requests to burst to
ip true Boolean Throttle on /32 (source id)
xff false Boolean Throttle on /32 X-Forwarded-For header
username false Boolean Throttle on req.username
overrides null Object Per "key" overrides
tokensTable - Object Storage engine
maxKeys 10000 Number Maximum distinct throttling keys to allow at a time


    burst: 10,
    rate: 0.5,
    ip: true,
    overrides: {
        '': {
            burst: 0,
            rate: 0    // unlimited
        '': {
            burst: 0,
            rate: 0

Handle Ratelimit errors

If a request with exceed the rate limit and cannot be processed, the next middleware will be invoked with an Error argument. The error instance will have a status field with code 429 and a message indicating the user has exceeded their quota You have exceeded your request rate of %s r/s.

You can handle this response by providing error handling middleware in your express app.

var app = express();

app.use(ratelimit({ ... });


app.use(function(err, req, res, next) {
   err.status // will be 429 if rate limited

   // example way to respond
   // NOTE, you will likely want to hide `err.message` for 5xx errors in production.
   res.status(err.stauts || 500).send(err.message);

Prior art

This module is repackaged code from the restify library throttle plugin for use with expressjs



See LICENSE.restify for restify's license.

Current Tags

  • 1.2.0                                ...           latest (5 years ago)

3 Versions

  • 1.2.0                                ...           5 years ago
  • 1.1.0                                ...           5 years ago
  • 1.0.0                                ...           6 years ago
Maintainers (1)
Today 0
This Week 0
This Month 1
Last Day 0
Last Week 1
Last Month 0
Dependencies (3)
Dev Dependencies (4)
Dependents (1)

Copyright 2014 - 2017 © taobao.org |