Next.js - Unkey Docs

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-appcd my-app

Install the SDK#

npm install @unkey/ratelimit

Add your root key#

Create or update .env.local:

.env.local

UNKEY_ROOT_KEY="unkey_..."

Warning

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 handlerconst 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

Test it#

# Hit the endpoint multiple timesfor 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.