Limites de taxa

O limite protege as rotas públicas: as que mandam e-mail, as que chamam um verificador pago e as que só têm o token do link como credencial. As rotas com Bearer não têm limite de taxa hoje.

A respostaCopy Anchor Link

HTTP/1.1 429 Too Many Requests
Retry-After: 2731
content-type: application/json

{ "success": false,
  "error": { "code": "RATE_LIMITED", "message": "too many requests",
             "details": { "retryAfterSeconds": 2731 } } }

Retry-After e details.retryAfterSeconds sempre têm o mesmo valor: os segundos que faltam pra janela acabar. O header é posto pelo errorHandler sempre que o erro é um TooManyRequestsError.

Rotas com limiteCopy Anchor Link

Cada regra dá um orçamento pelo identificador (e-mail, link ou token) e outro por IP. As duas contam, e a primeira que estourar responde 429. O formato da variável é limit/windowSeconds.

Login

Link de consentimento (por link e por IP)

Pareamento pelo celular da pessoa (números fixos no código, janela de 10 min)

As regras de uma hora lado a lado, com os padrões do env.ts:

Algumas escolhas:

• A evidência é limitada antes de ler o corpo. Um pedido recusado não custa o parse de um multipart grande.
• Nas rotas de consentimento, o limite roda antes de procurar o token. Testar tokens em sequência custa o mesmo que insistir num só.
• O orçamento por IP é mais folgado porque uma família costuma dividir o mesmo roteador.

ImplementaçãoCopy Anchor Link

backend/src/infra/rate-limit.ts é uma janela fixa no Redis:

1. INCR ratelimit:<chave>;
2. no primeiro acerto da janela, EXPIRE com windowSeconds;
3. passou do limit: lê o TTL e lança TooManyRequestsError(ttl). Se a chave ficou sem expiração (queda entre o INCR e o EXPIRE), ela ganha uma ali mesmo, pra ninguém ficar travado pra sempre.

É grosseira de propósito: o que importa é "mais ou menos tantos por janela". As chaves nunca guardam segredo em claro. Usam o SHA-256 do e-mail ou do token (otp:request:email:<sha>, consent:read:link:<hash>, pairing:start:link:<hash>) e o IP (…:ip:<ip>).

import { rateLimit } from "@infra/rate-limit.ts";
import { clientIp } from "../../request-meta.ts";

await rateLimit(`minha-rota:link:${hashToken(token)}`, {
  limit: 10,
  windowSeconds: 600,
});
await rateLimit(`minha-rota:ip:${clientIp(c)}`, {
  limit: 30,
  windowSeconds: 600,
});
// passou do limite → 429 RATE_LIMITED + Retry-After, pelo errorHandler

No cliente, use retryAfterSeconds pra mostrar a espera ("Tente de novo em N min") e pra controlar o botão de reenviar.

Ver o trecho de um alerta (POST /alerts/{uid}/excerpt) tem limite por responsável: 30 por minuto, chave alerts:excerpt:user:{id}. É a leitura mais sensível do sistema; o 429 traz o mesmo retryAfterSeconds.

FontesCopy Anchor Link

• backend/src/infra/rate-limit.ts, backend/src/http/request-meta.ts
• backend/src/http/routes/auth/limits.ts, backend/src/domains/auth/use-cases/request-otp.ts, resend-link.ts, code-lock.ts
• backend/src/http/routes/consents/limits.ts, pairing.route.ts, page.route.ts, evidence.route.ts, decline.route.ts, protection.route.ts
• backend/src/http/middleware/error-handler.ts, backend/src/core/contracts/errors.ts
• backend/src/config/env.ts, backend/.env.example
• Notas das frentes k-otp e k-pairing (k-otp-api.md, k-pairing-api.md)
• .specs/features/redesign/api-gaps.md (G-04, G-14)