Express

Step-by-step Express.js rate limiting tutorial with @unkey/ratelimit. Set per-route limits, return 429 responses, and skip the Redis dependency.

What you’ll build

An Express server with rate-limited endpoints. Users who exceed the limit get a 429 response.

Time to complete: ~5 minutes

Prerequisites

• Unkey account (free)
• Root key with ratelimit.*.limit permission
• Node.js 18+

1. Create your Express app

   mkdir unkey-express-ratelimit && cd unkey-express-ratelimit
   npm init -y
   npm install express @unkey/ratelimit dotenv
   
2. Add your root key

   Create a .env file:

   .env

   UNKEY_ROOT_KEY="unkey_..."
   

   Never commit your .env file. Add it to .gitignore.
3. Create your server

   Create index.js:

   index.js

   const express = require("express");
   const { Ratelimit } = require("@unkey/ratelimit");
   require("dotenv").config();
   
   const app = express();
   const port = process.env.PORT || 3000;
   
   // Create limiter instance
   const limiter = new Ratelimit({
     rootKey: process.env.UNKEY_ROOT_KEY,
     namespace: "express-api",
     limit: 10, // 10 requests...
     duration: "60s", // ...per minute
   });
   
   // Public route
   app.get("/", (req, res) => {
     res.json({ message: "Welcome! Try /api/data" });
   });
   
   // Rate-limited route
   app.get("/api/data", async (req, res) => {
     // 1. Identify the user (IP, user ID, API key, etc.)
     const identifier = req.headers["x-user-id"] || req.ip || "anonymous";
   
     // 2. Check the rate limit
     const { success, remaining, reset } = await limiter.limit(identifier);
   
     // 3. Set rate limit headers
     res.set({
       "X-RateLimit-Limit": "10",
       "X-RateLimit-Remaining": remaining.toString(),
       "X-RateLimit-Reset": reset.toString(),
     });
   
     if (!success) {
       return res.status(429).json({
         error: "Too many requests. Please try again later.",
         retryAfter: Math.ceil((reset - Date.now()) / 1000),
       });
     }
   
     // 4. Request allowed
     res.json({
       message: "Here's your data!",
       remaining,
     });
   });
   
   app.listen(port, () => {
     console.log(`Server running at http://localhost:${port}`);
   });
   
4. Run your server

   node index.js
   
5. Test it

   # Hit the endpoint 12 times
   for i in {1..12}; do
     curl http://localhost:3000/api/data -H "x-user-id: test-user"
     echo ""
   done
   

   First 10 requests succeed. Requests 11+ get:

   {
     "error": "Too many requests. Please try again later.",
     "retryAfter": 45
   }
   

What’s in the response?

limiter.limit() returns:

Field	Type	Description
success	boolean	true if allowed, false if rate limited
remaining	number	Requests left in current window
reset	number	Unix timestamp (ms) when window resets
limit	number	The configured limit

Using as middleware

For cleaner code, create reusable middleware:

middleware/ratelimit.js

const { Ratelimit } = require("@unkey/ratelimit");

const limiter = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY,
  namespace: "api",
  limit: 100,
  duration: "1m",
});

async function rateLimit(req, res, next) {
  const identifier = req.headers["x-user-id"] || req.ip || "anonymous";
  const { success, remaining, reset } = await limiter.limit(identifier);

  res.set({
    "X-RateLimit-Remaining": remaining.toString(),
    "X-RateLimit-Reset": reset.toString(),
  });

  if (!success) {
    return res.status(429).json({ error: "Rate limit exceeded" });
  }

  next();
}

module.exports = { rateLimit };

createMiddleware helper

Create an Express middleware from a Ratelimit instance:

function createMiddleware(limiter) {
  return async (req, res, next) => {
    const identifier = req.ip ?? req.headers["x-forwarded-for"] ?? "unknown";
    const { success, remaining, reset } = await limiter.limit(identifier);

    if (!success) {
      res.set("Retry-After", Math.ceil((reset - Date.now()) / 1000).toString());
      res.set("X-RateLimit-Remaining", "0");
      return res.status(429).json({ error: "Too many requests" });
    }

    res.set("X-RateLimit-Remaining", remaining.toString());
    next();
  };
}

Use on any route:

const { rateLimit } = require("./middleware/ratelimit");

app.get("/api/data", rateLimit, (req, res) => {
  res.json({ data: "protected content" });
});

app.post("/api/submit", rateLimit, (req, res) => {
  res.json({ success: true });
});

Different limits per route

Create multiple limiters:

const apiLimiter = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY,
  namespace: "api",
  limit: 100,
  duration: "1m",
});

const authLimiter = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY,
  namespace: "auth",
  limit: 5,
  duration: "1m",
});

// 100/min for general API
app.use("/api", createMiddleware(apiLimiter));

// 5/min for login (prevent brute force)
app.post("/login", createMiddleware(authLimiter), loginHandler);

Next steps

How it works

Understand the architecture

Per-user overrides

Give specific users higher limits

SDK Reference

All configuration options

Add API key auth

Combine with API key authentication

Troubleshooting

Rate limit not applying?

• Verify UNKEY_ROOT_KEY is set and has ratelimit.*.limit permission - Make sure you’re using a consistent identifier per user - Check that .env is loaded before creating the limiter

TypeScript version?

Install types and use imports:

npm install -D typescript @types/express @types/node

import express from "express";
import { Ratelimit } from "@unkey/ratelimit";