Upstash Ratelimit

Visão Geral

@upstash/ratelimit implementa limitação de taxa distribuída sobre o Upstash Redis. Como o estado reside no Redis, cada instância de uma função serverless ou worker de borda compartilha os mesmos contadores, o que um limitador em memória não consegue fazer. Ele oferece três algoritmos (janela fixa, janela deslizante, balde de tokens), chaves por identificador, bloqueio opcional em memória de identificadores já limitados e análise opcional.

Quando Usar Esta Habilidade

• Use quando o usuário precisar limitar requisições por IP, usuário, chave de API ou tenant entre múltiplas instâncias serverless ou regiões.
• Use ao proteger endpoints de login, cadastro, formulário, webhook ou LLM contra abusos e retornar 429 Too Many Requests.
• Use ao escolher entre janela fixa, janela deslizante e balde de tokens.
• Não use para retentativas/backoff do lado do cliente contra os limites de uma API de terceiros; veja api-rate-limit-handler.
• Não use para um único processo de longa execução sem estado compartilhado; um limitador em memória é mais simples nesses casos.

Como Funciona

Passo 1: Instalar e configurar

npm install @upstash/ratelimit @upstash/redis

Defina UPSTASH_REDIS_REST_URL e UPSTASH_REDIS_REST_TOKEN no ambiente.

Passo 2: Crie o limitador uma vez, fora do 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,
});

Construir o limitador no escopo do módulo permite que o cache efêmero embutido evite chamadas ao Redis para identificadores bloqueados.

Passo 3: Chame limit() com um identificador estável

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

success é false quando o identificador excede seu limite. reset é um timestamp Unix em milissegundos. pending é uma promessa para trabalho em segundo plano (análise, sincronização multi-região); aguarde-a ou passe-a para waitUntil em runtimes de borda para que a função não seja congelada antes de ser concluída.

Exemplos

Exemplo 1: Middleware Next.js retornando 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*" };

Exemplo 2: Balde de tokens com limites por plano

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);

Melhores Práticas

• ✅ Use um identificador estável e de baixa cardinalidade (ID de usuário, chave de API, tenant) onde for possível; recorra ao IP apenas para tráfego anônimo.
• ✅ Defina um prefix distinto por endpoint ou plano para que os limites não colidam.
• ✅ Retorne os cabeçalhos Retry-After e X-RateLimit-* com respostas 429.
• ✅ Prefira slidingWindow para a maioria das APIs; use tokenBucket quando rajadas curtas forem aceitáveis; use fixedWindow quando o menor custo de Redis for importante.
• ❌ Não construa um novo Ratelimit dentro do manipulador de requisição.
• ❌ Não confie que pending será concluído por conta própria em runtimes de borda.
• ❌ Não limite a taxa por x-forwarded-for sem validar que ele é definido pelo seu proxy; clientes podem falsificá-lo caso contrário.

Limitações

• Requer um banco de dados Upstash Redis; não funciona com outros servidores Redis ou sem acesso à rede.
• Cada chamada limit() é pelo menos uma viagem de ida e volta HTTP para o Redis, portanto, adiciona latência a cada requisição que ela protege.

…