Express Throttle

2.0.0 verified Sat Apr 25 auth: no javascript

Request throttling middleware for Express using a token bucket algorithm with sliding window refill. Version 2.0.0 is current stable. Enables per-route rate limiting with configurable burst capacity, rate, and key function (defaults to IP address). Supports half-requests and custom cost per request. Limitations: in-memory storage by default (not shared across processes), and race conditions when using custom external backends under high load. Recommended for single-process apps.

Common errors

error TypeError: throttle is not a function ↓

cause Importing as default ESM import (`import throttle from 'express-throttle'`) while package exports CommonJS.

fix

Use const throttle = require('express-throttle'); or import * as throttle from 'express-throttle';

error RangeError: Invalid rate string: '10/minutes' ↓

cause Rate string format is incorrect. Valid format: number/unit (e.g., '5/s', '10/m', '2/h'). Unit must be one of 's', 'm', 'h'.

fix

Use correct rate string like '10/m' for 10 per minute.

error Error: Cannot find module 'express-throttle' ↓

cause Package not installed.

fix

Run npm install express-throttle in your project directory.

Warnings

gotcha In-memory storage is not shared across multiple processes. Throttling is per-process when behind a load balancer. ↓

fix Use a shared external storage backend (e.g., Redis), but be aware of race conditions under high load. Alternatively, ensure sticky sessions.

deprecated The `period` option (fixed time window) is deprecated in favor of `rate` (sliding window). ↓

fix Use `rate` for sliding window throttling instead of `period`.

gotcha The default key function uses `req.ip`, which may return the load balancer's IP if not configured correctly. ↓

fix Configure Express trust proxy settings and provide a custom `key` function that uses `req.connection.remoteAddress` or `req.headers['x-forwarded-for']`.

gotcha Half requests (0.5 cost) are allowed but may lead to unexpected behavior if not integral tokens. ↓

fix Use integer `cost` values to avoid fractional token counting.

gotcha External storage backends have race conditions; high load may cause erroneous throttling or allowing requests. ↓

fix Use in-memory storage for single-process apps, or wait for a future version with atomic operations.

Install

npm install express-throttle

yarn add express-throttle

pnpm add express-throttle

Imports

throttle
wrong
```
import throttle from 'express-throttle';
```
correct
```
const throttle = require('express-throttle');
```
Package uses CommonJS; no default ESM export. For TypeScript, use `import throttle = require('express-throttle');` or `const throttle = require('express-throttle');`.

Quickstart

Basic Express app with three rate-limited routes using express-throttle middleware.

const express = require('express');
const throttle = require('express-throttle');

const app = express();

// Allow 5 requests per second with a burst of 10
app.get('/api', throttle({ burst: 10, rate: '5/s' }), (req, res) => {
  res.json({ status: 'ok' });
});

// Allow 3 requests per minute (sliding window)
app.post('/search', throttle({ rate: '3/m' }), (req, res) => {
  res.json({ result: 'search done' });
});

// Custom key function (by session username)
app.use('/user', throttle({
  burst: 5,
  rate: '1/s',
  key: (req) => req.session?.username ?? req.ip
}), (req, res) => {
  res.json({ user: req.session.username });
});

app.listen(3000);