How do I add Upstash rate limiting to a Next.js API route on Vercel?

The route handler code

Create the limiter once in its own file and call it first in each route that costs money. @upstash/ratelimit sends its commands through an @upstash/redis client, so it needs the same two environment variables.

// lib/ratelimit.ts
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

export const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "10 s"),
  prefix: "chat",
});

// app/api/chat/route.ts
import { ratelimit } from "@/lib/ratelimit";

export async function POST(request: Request) {
  const ip = request.headers.get("x-forwarded-for") ?? "anonymous";
  const { success, reset } = await ratelimit.limit(ip);
  if (!success) {
    const retryAfter = Math.ceil((reset - Date.now()) / 1000);
    return new Response("Too many requests", {
      status: 429,
      headers: { "Retry-After": String(retryAfter) },
    });
  }
  // the paid call goes here
}

Which identifier to use: the IP or the user ID

On Vercel, x-forwarded-for holds the public IP of the client, and x-real-ip carries the same value. The Vercel docs say that behind a proxy Vercel overwrites X-Forwarded-For and does not forward external IPs, to prevent IP spoofing. Off Vercel, or behind your own proxy, find out which hop sets the header before you trust it. When the header is missing, the code above puts every such request in one "anonymous" bucket. On signed-in routes, pass the user ID instead, so people on one network do not share a limit.

Should the limit live in proxy.ts or in the route?

Next.js 16 renamed middleware.ts to proxy.ts and runs it on the Node.js runtime by default. With a matcher of /api/:path*, one proxy limits every route under it. Without a matcher it runs on every request, and the example matcher in the Next.js docs excludes api, so read yours. Next.js also says Server Functions run as POST requests to the route where they are used, so a matcher that skips a path skips its actions too. A call inside the route handler or the action covers exactly that code.

// proxy.ts (middleware.ts before Next.js 16)
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { ratelimit } from "@/lib/ratelimit";

export async function proxy(request: NextRequest) {
  const ip = request.headers.get("x-forwarded-for") ?? "anonymous";
  const { success } = await ratelimit.limit(ip);
  if (!success) return new NextResponse("Too many requests", { status: 429 });
  return NextResponse.next();
}

export const config = { matcher: "/api/:path*" };

What limit() does when Redis is missing or slow

With no URL or token, limit() throws "TypeError: Failed to parse URL from /pipeline" on Node.js 24, so the route answers 500 and no request passes. The cause and fix are in [Upstash Redis] Unable to find environment variable: UPSTASH_REDIS_REST_URL. When Redis answers slowly, the Upstash docs describe a timeout, 5 seconds by default, after which the request is allowed through whatever the current limit is; the result then has reason set to "timeout".

Checklist

Add the limit, then check it

1. 01
   Find API routes with no rate limiter in the repo. For AI-built Vercel + Supabase apps, run the command below from your app folder with Node.js 20 or newer. It reports missing_rate_limit as a warning when the repo has API routes and no rate limiting package or limiter code.

   npx -y viberaven@1.7.1 check

2. 02In the Upstash console, open a Redis database and copy its REST URL and REST token from the Connect section.
3. 03
   Install the packages:

   npm install @upstash/ratelimit @upstash/redis

4. 04Add UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN to .env.local, to .env.example without values, and in the Vercel project's Environment Variables for Production and Preview.
5. 05Create the Ratelimit in one file, call limit() first in each route or server action that costs money, and return 429 when success is false.
6. 06Redeploy, then call a copy of the route that skips the paid call in a loop from a terminal, because the first requests inside the limit run it. After 10 requests in 10 seconds in this example, the answers change to 429.

Related

Related guides

• Do my Next.js API routes have rate limiting, and how do I check?Guide
• How do I secure a vibe-coded app?Guide
• VercelWhich env vars does my app read that are missing in Vercel production?Guide

Sources

Official docs behind this checklist

• Upstash Ratelimit, Getting started
• Upstash Ratelimit, Algorithms
• Upstash Ratelimit, Features (timeout, caching, analytics)
• Upstash Ratelimit, Methods and response fields
• @upstash/ratelimit, src/ratelimit.ts
• Vercel, Request headers (x-forwarded-for, x-real-ip)
• Vercel, Environment variables
• Next.js, proxy.js (matcher, execution order, Server Functions)

FAQ

FAQ for builders before launch