Next.js

What you’ll build

A Next.js API route that limits each user to a set number of requests per time window. Excess requests get rejected with a 429. Time to complete: ~5 minutes

Prerequisites

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

Create a Next.js app

Skip if you have an existing project.

npx create-next-app@latest my-app
cd my-app

pnpm create next-app@latest my-app
cd my-app

bunx create-next-app my-app
cd my-app

Install the SDK

npm install @unkey/ratelimit

pnpm add @unkey/ratelimit

bun add @unkey/ratelimit

Add your root key

Create or update .env.local:

.env.local

UNKEY_ROOT_KEY="unkey_..."

Never commit your root key. Add .env.local to .gitignore.

Create a rate-limited route

app/api/protected/route.ts

import { NextResponse } from "next/server";
import { Ratelimit } from "@unkey/ratelimit";

// Create limiter instance outside the handler
const limiter = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY!,
  namespace: "my-app", // Group related limits
  limit: 10, // 10 requests...
  duration: "60s", // ...per minute
});

export async function POST(req: Request) {
  // 1. Identify the user (IP, user ID, API key, etc.)
  const identifier =
    req.headers.get("x-user-id") ??
    req.headers.get("x-forwarded-for") ??
    "anonymous";

  // 2. Check the rate limit
  const { success, remaining, reset } = await limiter.limit(identifier);

  // 3. Add rate limit headers (optional but nice for clients)
  const headers = {
    "X-RateLimit-Limit": "10",
    "X-RateLimit-Remaining": remaining.toString(),
    "X-RateLimit-Reset": reset.toString(),
  };

  if (!success) {
    return NextResponse.json(
      { error: "Too many requests. Please try again later." },
      { status: 429, headers },
    );
  }

  // 4. Request allowed, do your thing
  return NextResponse.json({ message: "Hello!", remaining }, { headers });
}

Run your app

npm run dev

pnpm dev

bun dev

Test it

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

First 10 requests return 200. Requests 11+ return 429:

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

Wait 60 seconds and the limit resets.

What’s in the response?

limiter.limit() returns:

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

Choosing an identifier

The identifier determines who gets rate limited. Common choices:

Identifier	Use case	Example
User ID	Authenticated users	`req.auth.userId`
API key	Per-key limits	`req.headers.get("x-api-key")`
IP address	Anonymous/public endpoints	`req.headers.get("x-forwarded-for")`
Combo	Extra specificity	`${userId}:${endpoint}`

Creating a reusable limiter

For cleaner code, create a utility:

lib/ratelimit.ts

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

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

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

Then use in routes:

app/api/login/route.ts

import { authLimiter } from "@/lib/ratelimit";

export async function POST(req: Request) {
  const ip = req.headers.get("x-forwarded-for") ?? "unknown";
  const { success } = await authLimiter.limit(ip);

  if (!success) {
    return Response.json({ error: "Too many login attempts" }, { status: 429 });
  }

  // Handle login...
}

Next steps

How it works

Understand the rate limiting architecture

Per-user overrides

Give specific users higher limits

SDK Reference

All configuration options

Add API key auth

Combine rate limiting with authentication

Troubleshooting

Rate limit not working?

Check that UNKEY_ROOT_KEY is set in .env.local - Verify your root key has ratelimit.*.limit permission - Make sure you’re using the same identifier each request - Restart the dev server after changing .env.local

Getting network errors?

Unkey’s SDK retries failed requests automatically - If errors persist, check status.unkey.com - Check status.unkey.com if issues persist

Want different limits per route?

Create multiple Ratelimit instances with different namespaces and limits. Each namespace tracks limits independently.

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

What you’ll build

Prerequisites

Create a Next.js app

Install the SDK

Add your root key

Create a rate-limited route

Run your app

Test it

What’s in the response?

Choosing an identifier

Creating a reusable limiter

Next steps

How it works

Per-user overrides

SDK Reference

Add API key auth

Troubleshooting

​What you’ll build

​Prerequisites

Create a Next.js app

Install the SDK

Add your root key

Create a rate-limited route

Run your app

Test it

​What’s in the response?

​Choosing an identifier

​Creating a reusable limiter

​Next steps

How it works

Per-user overrides

SDK Reference

Add API key auth

​Troubleshooting

What you’ll build

Prerequisites

What’s in the response?

Choosing an identifier

Creating a reusable limiter

Next steps

Troubleshooting