Add Rate Limiting and Bot Protection to a Node.js API with Arcjet

What you'll build

An Express API protected by Arcjet: per-IP rate limiting, bot detection that blocks scrapers while letting search engines through, and a WAF layer against SQL injection and XSS. One middleware function, about 40 lines, and no Redis cluster to babysit because Arcjet's cloud tracks the counters.

Prerequisites

• Node.js 22.21.0 or newer on the 22 line, or 24.5.0+. Not 23.x. @arcjet/node 1.11.0 declares engines: ">=22.21.0 <23 || >=24.5.0", and if your Node doesn't satisfy that range, npm quietly resolves an older SDK release instead (see Troubleshooting).
• A free Arcjet account. Sign up at console.arcjet.com; no credit card needed.
• Arcjet is ESM-only. CommonJS require() won't work, so the project below sets "type": "module".

Verified against @arcjet/node 1.11.0, @arcjet/inspect 1.11.0, and Express 5.2.1 on macOS.

1. Create the project

mkdir arcjet-demo && cd arcjet-demo
npm init -y
npm pkg set type=module
npm install @arcjet/node@1.11.0 @arcjet/inspect@1.11.0 express@5

@arcjet/inspect is optional but small; it adds helpers for catching clients that fake a Googlebot user agent.

2. Get an Arcjet key

In the Arcjet console, create a site and copy its key from the SDK installation tab. It starts with ajkey_.

Create .env.local in the project root:

ARCJET_KEY=ajkey_yourkeyhere
ARCJET_ENV=development

ARCJET_ENV=development tells the SDK to accept private addresses like 127.0.0.1 as the client IP, which every local request has. Without it, requests fail fingerprinting. Remove it in production so real client IPs are enforced.

3. Write the middleware

Create index.js:

import arcjet, { detectBot, shield, slidingWindow } from "@arcjet/node";
import { isSpoofedBot } from "@arcjet/inspect";
import express from "express";

const app = express();
const port = 3000;

const aj = arcjet({
  key: process.env.ARCJET_KEY,
  rules: [
    // Shield blocks common attacks like SQL injection and XSS
    shield({ mode: "LIVE" }),
    // Block all bots except search engine crawlers and link previews
    detectBot({
      mode: "LIVE", // "DRY_RUN" logs decisions without blocking
      allow: ["CATEGORY:SEARCH_ENGINE", "CATEGORY:PREVIEW"],
    }),
    // Max 5 requests per 10 seconds per IP
    slidingWindow({
      mode: "LIVE",
      interval: "10s",
      max: 5,
    }),
  ],
});

// Run Arcjet on every request before it reaches a route
app.use(async (req, res, next) => {
  const decision = await aj.protect(req);

  if (decision.isDenied()) {
    if (decision.reason.isRateLimit()) {
      return res.status(429).json({ error: "Too many requests" });
    }
    if (decision.reason.isBot()) {
      return res.status(403).json({ error: "Bots are not allowed" });
    }
    return res.status(403).json({ error: "Forbidden" });
  }

  // Catch clients pretending to be Googlebot etc.
  if (decision.results.some(isSpoofedBot)) {
    return res.status(403).json({ error: "Bot spoofing detected" });
  }

  next();
});

app.get("/api/hello", (req, res) => {
  res.json({ message: "hello" });
});

app.listen(port, () => {
  console.log(`API listening on http://localhost:${port}`);
});

Shield and bot detection run inside the SDK's WebAssembly analyzer on your server, so they add near-zero latency. The sliding window counter lives in Arcjet's cloud, keyed by client IP by default; a sliding window avoids the burst-at-the-boundary problem fixed windows have. If the Arcjet API is unreachable the SDK fails open and allows the request, which is the behavior you want from a third-party dependency in the hot path.

The full list of bot categories and individual bots you can allow or deny is at arcjet.com/bot-list.

4. Start the API

Node 20.6+ reads env files natively, so you don't need dotenv:

node --env-file .env.local index.js

Expected output:

✦Aj WARN Arcjet will use 127.0.0.1 when missing public IP address in development mode
API listening on http://localhost:3000

The warning is normal in development mode.

Verify it works

Test the rate limit first and the bot block second. Deny decisions are cached against your IP fingerprint for up to 60 seconds, and in development every local request shares the 127.0.0.1 fingerprint, so a curl bot-block bleeds into your next test if you run them in the other order.

Send 7 quick requests with a browser user agent (plain curl would trip the bot rule instead):

for i in $(seq 1 7); do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36" \
    http://localhost:3000/api/hello
done

Expected: five 200s, then 429 for the rest of the 10-second window.

200
200
200
200
200
429
429

Now the bot rule. Wait 15 seconds for the window to reset, then hit the API with curl's default user agent:

curl -s -w "\n%{http_code}\n" http://localhost:3000/api/hello

Expected:

{"error":"Bots are not allowed"}
403

Open http://localhost:3000/api/hello in a real browser and you'll get {"message":"hello"}. Every request also shows up in the Arcjet console under your site, with the rule that matched and why, which is where you'll debug rules later.

Troubleshooting

Everything returns 403 after you tested with curl. The bot deny was cached for 60 seconds against your IP fingerprint, and locally all requests share it, so even browser requests get the cached deny. Wait a minute or restart the server; the cache is in-process memory.

✦Aj ERROR [unauthenticated] invalid key (or decision.conclusion is "ERROR" with [unauthenticated] unauthorized). Your ARCJET_KEY is wrong or empty. Copy it again from the site's SDK installation tab in the console; it must start with ajkey_. Note the SDK fails open here: requests are allowed while the key is bad, so bot blocking appears to work (it's local) but rate limiting silently doesn't.

generateFingerprint: ip is empty or [failed_precondition] client IP not provided. You're running locally without ARCJET_ENV=development, so the SDK refuses 127.0.0.1 as a client IP. Add it to .env.local.

npm installed @arcjet/node 1.5.0 instead of 1.11.0. Your Node version doesn't satisfy the SDK's engines range, and npm resolves the newest version that claims support for your runtime instead of the actual latest. node --version should print 22.21.0+ (below 23) or 24.5.0+; upgrade, delete node_modules and package-lock.json, and reinstall.

Next steps

The sliding window here limits by IP, which is right for anonymous traffic. For authenticated APIs, add characteristics: ["userId"] to the rule and pass userId into aj.protect(req, { userId }) so each user gets their own bucket; the rate limiting reference covers this plus the token bucket and fixed window algorithms. Before enforcing in production, flip rules to mode: "DRY_RUN" and watch decisions in the console to see what would have been blocked. The Node.js SDK reference documents the other protections in the same SDK: email validation, sensitive-data redaction, and signup form protection.