Upstash Ratelimit

Overview

@upstash/ratelimit implements distributed rate limiting on top of Upstash Redis. Because state lives in Redis, every instance of a serverless function or edge worker shares the same counters, which an in-memory limiter cannot do. It ships three algorithms (fixed window, sliding window, token bucket), per-identifier keys, optional in-memory blocking of already-limited identifiers, and optional analytics.

When to Use This Skill

• Use when the user needs to limit requests per IP, user, API key, or tenant across multiple serverless instances or regions.
• Use when protecting login, signup, form, webhook, or LLM endpoints from abuse and returning 429 Too Many Requests.
• Use when choosing between fixed window, sliding window, and token bucket.
• Do not use for client-side retry/backoff against a third-party API's limits; see api-rate-limit-handler.
• Do not use for a single long-running process with no shared state; an in-memory limiter is simpler there.

How It Works

Step 1: Install and configure

npm install @upstash/ratelimit @upstash/redis

Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN in the environment.

Step 2: Create the limiter once, outside the handler

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

export const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "10 s"), // 10 requests per 10 seconds
  prefix: "rl:api",
  analytics: true,
});

Constructing the limiter at module scope lets the built-in ephemeral cache short-circuit blocked identifiers without a Redis call.

Step 3: Call limit() with a stable identifier

const { success, limit, remaining, reset, pending } = await ratelimit.limit(userId);

success is false when the identifier is over its limit. reset is a Unix timestamp in milliseconds. pending is a promise for background work (analytics, multi-region sync); await it or pass it to waitUntil on edge runtimes so the function is not frozen before it completes.

Examples

Example 1: Next.js middleware returning 429

import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";
import { NextResponse, type NextRequest } from "next/server";

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(20, "1 m"),
});

export async function middleware(request: NextRequest) {
  const ip = request.headers.get("x-forwarded-for") ?? "anonymous";
  const { success, limit, remaining, reset } = await ratelimit.limit(ip);

  if (!success) {
    return new NextResponse("Too Many Requests", {
      status: 429,
      headers: {
        "X-RateLimit-Limit": String(limit),
        "X-RateLimit-Remaining": String(remaining),
        "X-RateLimit-Reset": String(reset),
        "Retry-After": String(Math.ceil((reset - Date.now()) / 1000)),
      },
    });
  }
  return NextResponse.next();
}

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

Example 2: Token bucket with per-plan limits

const limiters = {
  free: new Ratelimit({
    redis: Redis.fromEnv(),
    prefix: "rl:free",
    limiter: Ratelimit.tokenBucket(5, "10 s", 10), // refill 5 per 10 s, burst 10
  }),
  pro: new Ratelimit({
    redis: Redis.fromEnv(),
    prefix: "rl:pro",
    limiter: Ratelimit.tokenBucket(50, "10 s", 100),
  }),
};

const { success } = await limiters[plan].limit(apiKey);

Best Practices

• ✅ Use a stable, low-cardinality identifier (user id, API key, tenant) where possible; fall back to IP only for anonymous traffic.
• ✅ Set a distinct prefix per endpoint or plan so limits do not collide.
• ✅ Return Retry-After and X-RateLimit-* headers with 429 responses.
• ✅ Prefer slidingWindow for most APIs; use tokenBucket when short bursts are acceptable; use fixedWindow when the lowest Redis cost matters.
• ❌ Don't construct a new Ratelimit inside the request handler.
• ❌ Don't rely on pending completing on its own in edge runtimes.
• ❌ Don't rate limit by x-forwarded-for without validating it is set by your proxy; clients can spoof it otherwise.

Limitations

• Requires an Upstash Redis database; it does not work with other Redis servers or without network access.
• Each limit() call is at least one HTTP round trip to Redis, so it adds latency to every request it guards.
• Sliding window is an approximation that assumes an even spread of requests in the previous window; it is not an exact log.
• MultiRegionRatelimit trades strict accuracy for lower latency and does not support the token bucket algorithm.
• If Redis is unreachable, the default timeout (5 s) lets requests through (reason: "timeout"); this fails open, not closed.
• This skill does not replace environment-specific validation, testing, or expert review.

Security & Safety Notes

• Rate limiting is one layer of abuse protection, not authentication. Pair it with auth and input validation.
• The Redis token grants full database access; keep it server-side.
• Changing limits in production can lock out legitimate users. Confirm the numbers with the user before deploying stricter limits.

Common Pitfalls

• Problem: Every request is allowed even after the limit. Solution: Each identifier must be the same string across requests; check that the identifier is not undefined or a fresh random value.
• Problem: Analytics are empty on Vercel Edge or Cloudflare Workers. Solution: Pass pending to waitUntil (ctx.waitUntil(pending)) so the background request is not cancelled when the response is sent.

Related Skills

• @upstash-redis - The client this package uses for storage.
• @api-rate-limit-handler - Client-side backoff and retry when you are the one being rate limited.
• @upstash-qstash - Queue and smooth traffic to downstream services instead of rejecting it.

Additional Resources

• Upstash Ratelimit documentation
• @upstash/ratelimit on GitHub
• Algorithms guide