Um rate limit define como a capacidade compartilhada será dividida: quem usa, como picos são tratados, o que ocorre no limite e como o cliente se recupera. Um “100 requisições por minuto” genérico pode proteger o serviço e ainda punir lotes normais, ignorar endpoints caros ou fazer retries amplificarem uma falha.
Comece pelo motivo: proteger banco, isolar tenants, limitar chamada cara de IA, evitar abuso de credenciais ou cumprir uma cota contratual. São políticas diferentes e podem exigir contadores separados. Cota de usuário deve ser explicável; limite de proteção contra sobrecarga pode ser curto e adaptativo.
| Contador | Protege | Problema se usado sozinho |
|---|---|---|
| Requisições por chave/conta | Acesso justo e contenção de abuso. | Leitura barata e gravação cara valem igual. |
| Unidades ponderadas por cliente | Custo de banco, compute ou IA. | Peso pode se afastar do consumo real. |
| Trabalho simultâneo | Workers, conexões e tarefas longas. | Não limita consumo diário. |
| Orçamento global | Infraestrutura compartilhada em picos. | Um cliente barulhento pode excluir os demais. |
| Cota comercial | Plano ou consumo pago. | Precisa refletir cobrança e regras de reset. |
APIs maduras combinam camadas: justiça por chave ou tenant, pesos por endpoint, limite de concorrência e teto global de emergência. Autentique antes do controle por usuário. Limites por IP ajudam no abuso anônimo, mas penalizam gente atrás de NAT compartilhado.
Janela fixa é simples, mas permite pico nas bordas do reset. Log deslizante é preciso e guarda mais eventos; contador aproximado reduz estado. Token bucket permite pico definido e limita taxa sustentada. Leaky bucket suaviza a saída. Limite de concorrência restringe trabalho simultâneo e complementa taxa. Escolha conforme comportamento desejado, custo e necessidade de consistência.
HTTP 429 significa excesso de requisições. RFC 6585 recomenda explicar a condição e permite Retry-After. Retorne código de erro estável e prazo quando útil. Metadados de limite ajudam cliente a planejar, sem expor uso de outro tenant ou capacidade interna. A resposta 429 não deve ser cacheada como resultado normal.
SDKs devem respeitar Retry-After, usar backoff exponencial com jitter, limitar tentativas e evitar repetir mutação sem chave idempotente. Retries sincronizados criam avalanche durante recuperação. APIs em lote podem oferecer tamanho máximo ou job assíncrono em vez de obrigar milhares de chamadas pequenas.
Contador em processo local é rápido, mas reinício o zera e réplicas divergem. Contador central compartilha visão, mas adiciona latência e dependência. Controle na borda escala geograficamente, mas exige repartir orçamento e tolerar excesso limitado. Decida o que pesa mais quando o contador falha: quota global estrita ou disponibilidade. Documente fail-open/fail-closed por endpoint e risco.
Cota comercial deve vir de eventos duráveis ou ledger, não apenas de contador temporário de throttle. Rate limit protege serviço; não é automaticamente medição confiável de cobrança.
Documente cotas por plano, picos, custo por endpoint, concorrência, resets, paginação e retries. Exponha uso aos responsáveis pela conta e avise antes de bloquear quando possível. Versione mudanças com janela de migração. Suporte precisa diferenciar limite, indisponibilidade, falha de autenticação e saldo esgotado.
Acompanhe 429 por cliente/rota, custo aceito, saturação de filas/conexões, amplificação por retry, latência e conclusão do negócio. Requisições repetidamente limitadas apesar de média baixa podem indicar picos, pressupostos de relógio ou contador compartilhado injusto. Teste vizinho barulhento, bursts sincronizados e indisponibilidade do armazenamento do limitador.
Rate limits definem como clientes se integram. Determine primeiro risco e capacidade, escolha contadores e algoritmos adequados, aplique escopos em camadas, explique o 429 e especifique o comportamento quando o estado de enforcement falha. Bons limites preservam acesso justo e dão ao cliente correto um caminho previsível para concluir.