Should I use Redis or an in-memory Map?

Use an in-memory Map only on a single Node process. Use Redis (local or hosted) as soon as you have multiple instances, serverless isolates, or an agent gateway.

What status should agents receive when limited?

HTTP 429 with a Retry-After header and a small JSON body. Document that contract in the tool description so the model backs off instead of retrying immediately.

Do Server Actions need the same limiter?

Yes. A Server Action is still an HTTP endpoint. Apply the same identity key and budget after you resolve the session.

Rate Limit Next.js 16 Route Handlers Before AI Agents Melt Your API (2026)

Your Route Handler is a public function. Treat it like one.

In 2026 a Next.js Route Handler is no longer only hit by browsers. Scrapers, coding agents, MCP hosts, and retrying mobile clients all call the same POST. If that handler talks to Postgres, Stripe, Resend, or a model API, unbounded traffic is a bill and an outage, not a hypothetical.

This guide is the production pattern I use on self-hosted and serverless Next.js 16 apps: identify the caller, apply a sliding-window limit close to the edge, fail closed on abuse, and fail open only when the limiter itself is down and the endpoint is cheap.

What you will implement

A small TypeScript limiter that works in Node Route Handlers
Redis sliding windows for multi-instance deploys
A process-local Map fallback for single-VPS apps
Separate budgets for anonymous IP, authenticated user, and agent tokens
Correct 429 responses with Retry-After

1. What to rate limit

Limit every path that has a side effect or a paid dependency:

Contact forms and lead capture
Auth start, magic links, password reset
Search that hits Postgres or OpenSearch
Agent write or tool gateways
Image or AVIF transforms if you self-host the optimizer

Do not rate limit static assets or cached GET pages at the application layer. That belongs in Nginx or a CDN.

2. Identity comes first

A limit key is only as good as the identity behind it.

Authenticated user — session user id. Best key.
Agent principal — hashed API token or OAuth client id. Never log the raw secret.
Anonymous — hashed client IP plus User-Agent prefix. Behind Nginx, read X-Forwarded-For only from a trusted proxy.

Never trust a body field named userId. The model or client will invent one.

3. Algorithm

Use a sliding window counter in Redis. Fixed windows are simpler and fail at the boundary: 60 requests at 00:59 and 60 more at 01:00. Token buckets are excellent for smoothing bursts; sliding windows are easier to reason about in support tickets.

Recommended starting budgets:

Public contact POST: 5 / 10 minutes / IP
Authenticated writes: 30 / minute / user
Agent tools: 20 / minute / token, plus a daily cap

4. Redis sliding window

On a VPS, run Redis next to the Node process. On serverless, use a hosted Redis with REST so each isolate does not hold a stale TCP pool. The handler should INCR a key like rl:contact:{ipHash}:{window} and EXPIRE it on first write. If the count exceeds the budget, return 429.

Hash IPs with a server-side salt so access logs and rate-limit keys cannot be joined by a third party who only sees one of them.

5. Single-VPS fallback

If you run one Node process behind Nginx and PM2, an in-memory Map is acceptable for low-value forms. It resets on deploy and does not work across instances. Promote to Redis the moment you add a second process or an agent gateway.

Evict keys older than two windows so the Map cannot grow without bound.

6. Next.js wiring

Call the limiter at the top of the Route Handler after you read headers and before you parse a large JSON body. For Server Actions, run the same helper inside the action after requireSession. Do not put rate limits only in middleware if the action can also be invoked from a server component path you forgot to wrap.

Response shape:

Status 429
Retry-After in seconds
JSON { error: "rate_limited", retryAfterSec }

Do not include internal Redis errors in the body.

7. Agent endpoints need two clocks

Agents retry. A single tight window creates thundering herds. Give agents:

A short window for burst control
A daily quota so a stuck loop cannot spend the model budget
Idempotency keys on writes so retries do not double-apply after a 200

Pair this with the write-gateway pattern in the Postgres agent guide. Rate limits stop volume. Policy stops bad rows.

8. Nginx still matters

Application limits are not a substitute for connection limits. On a VPS, cap request rate and concurrent connections per IP at Nginx for /api/. That stops cheap floods from reaching Node before Redis is even consulted.

9. Observability

Log limiter decisions as structured events: route, key type (user | agent | ip), result (allow | deny), remaining. Alert when deny rate jumps, not when a single scraper is blocked. If Redis is unreachable, decide per route: fail open for a read-only search, fail closed for auth and payments.

10. Common mistakes

Keying only on IP while the product is behind CGNAT or a corporate egress.
Rate limiting after the expensive work already ran.
Sharing one budget across login and contact so an attacker locks real users out.
Returning 200 with an error string so agents keep retrying immediately.
Storing raw access tokens as Redis keys.

11. FAQ

Is middleware enough?

Middleware is a good first filter for anonymous routes. Authenticated and agent routes should still check inside the handler where you have the session.

Can I use Vercel KV / Upstash only?

Yes on serverless. On a single VPS, local Redis is cheaper and has fewer moving parts.

Should I rate limit Server Actions the same way?

Yes. A Server Action is an HTTP endpoint with a different URL shape. It needs the same identity and budget.

What status code should agents expect?

429 with Retry-After. Document it in the tool description so the model backs off instead of inventing a new payload.

12. Summary

Rate limiting is not a library choice. It is an identity, budget, and failure-mode decision. Put a sliding window in front of every expensive Route Handler, give agents two clocks, and keep Nginx in the path on a VPS.

Key takeaway

If a stranger can POST it, it needs a budget. If an agent can POST it, it needs a smaller budget and an idempotency key.

Need production API hardening on Next.js?

I build Route Handlers, agent gateways, and VPS edge configs for teams that cannot absorb unbounded traffic. Get in touch or review full-stack services.