Limitação de taxa para APIs públicas: quotas práticas e fluxos de bloqueio

Qual problema a limitação de taxa realmente resolve

A limitação de taxa para APIs públicas não existe para punir usuários. É uma válvula de segurança que mantém seu serviço disponível quando o tráfego fica estranho, seja esse "estranho" malicioso ou apenas um bug no cliente.

"Abuso" muitas vezes parece normal a princípio: um scraper que percorre todos os endpoints para copiar dados, tentativas de login por força bruta, token stuffing contra rotas de autenticação ou um cliente descontrolado que tenta a mesma requisição em loop apertado após um timeout. Às vezes ninguém está realmente atacando você. Uma atualização de app móvel pode vir com uma regra de cache ruim e, de repente, todos os dispositivos consultam sua API a cada segundo.

O trabalho é direto: proteger o uptime e controlar custos sem bloquear usuários reais que fazem trabalho normal. Se seu backend é cobrado por uso (compute, banco de dados, email/SMS, chamadas a AI), um ator barulhento pode inflar a conta rapidamente.

Sozinha, a limitação de taxa também não basta. Sem monitoramento e respostas de erro claras, você tem falhas silenciosas, clientes confusos e tickets de suporte que soam como "sua API está caída" quando na verdade está sendo limitada.

Uma proteção completa costuma ter alguns pedaços separados:

• Rate limits: limites em janelas curtas (por segundo/minuto) que bloqueiam picos.
• Quotas: orçamentos em janelas longas (por dia/mês) que mantêm o uso previsível.
• Lockouts: bloqueios temporários para padrões claramente abusivos.
• Exceções: allowlists para integrações confiáveis, ferramentas internas ou clientes VIP.

Se você está construindo um backend de API em uma plataforma como AppMaster, essas regras continuam importantes. Mesmo com código limpo e regenerado, você vai querer defaults protetores para que um cliente ruim não derrube todo o serviço.

Termos-chave: rate limits, quotas, throttling e lockouts

Esses termos se misturam, mas resolvem problemas diferentes e soam diferentes para os usuários.

Rate limit, quota e concorrência: o que cada um significa

Um rate limit é um limite de velocidade: quantas requisições um cliente pode fazer em uma janela curta (por segundo, por minuto). Uma quota é um orçamento: uso total em um período mais longo (por dia, por mês). Um limite de concorrência limita quantas requisições podem estar em progresso ao mesmo tempo, útil para endpoints caros mesmo quando a taxa de requisições parece normal.

Onde você aplica o limite importa:

• Por IP: simples, mas penaliza redes compartilhadas (escritórios, escolas, operadoras móveis).
• Por usuário: ótimo para apps logados, mas depende de identidade confiável.
• Por chave de API: comum em APIs públicas, propriedade clara e fácil de comunicar.
• Por endpoint: útil quando uma rota é muito mais pesada que as outras.

Throttling vs bloqueio, e onde os lockouts se encaixam

Throttling suave desacelera o cliente (atrasos, menor capacidade de burst) para que ele se recupere sem quebrar fluxos. Bloqueio duro rejeita requisições imediatamente, geralmente com HTTP 429.

Um lockout é mais forte que um 429 normal. Um 429 diz "tente de novo em breve." Um lockout diz "pare até que uma condição seja atendida", como um período de cooldown, revisão manual ou reset da chave. Reserve lockouts para sinais claros de abuso (credential stuffing, scraping agressivo, autenticações inválidas repetidas), não para picos de tráfego normais.

Se você está construindo uma API com uma ferramenta como AppMaster, trate-os como controles separados: limites de janela curta para bursts, quotas mais longas para custo, e lockouts apenas para comportamento repetidamente ruim.

Escolhendo limites práticos sem chutar números

Bons limites começam com um objetivo: proteger o backend enquanto permitem que usuários normais terminem seu trabalho. Você não precisa de números perfeitos no primeiro dia. Precisa de uma base segura e de uma forma de ajustá-la.

Um ponto de partida simples é um limite por chave de API que combine com o tipo de API que você roda:

• Baixo tráfego: 60–300 requisições por minuto por chave
• Tráfego médio: 600–1.500 requisições por minuto por chave
• Alto tráfego: 3.000–10.000 requisições por minuto por chave

Depois divida limites por tipo de endpoint. Reads costumam ser mais baratos e podem ter limites maiores. Writes mudam dados, frequentemente disparam lógica extra, e merecem limites mais apertados. Um padrão comum é algo como 1.000/min para rotas GET, mas 100–300/min para POST/PUT/DELETE.

Também identifique endpoints caros e trate-os separadamente. Search, geração de relatórios, exports, uploads de arquivos e qualquer coisa que toque muitas tabelas ou rode lógica pesada deve ter um bucket menor mesmo se o resto da API for generoso. Se seu backend usa fluxos visuais (por exemplo, Business Process flows), cada passo extra é trabalho real que se multiplica sob carga.

Planeje bursts com duas janelas: uma curta para absorver picos rápidos e outra mais longa que mantenha o uso sustentado sob controle. Uma combinação comum é 10 segundos mais 10 minutos. Isso ajuda usuários reais que clicam rápido, sem dar velocidade ilimitada a scrapers.

Finalmente, decida o que acontece quando o cliente excede o limite. A maioria das APIs públicas retorna HTTP 429 com um tempo claro de retry. Se o trabalho for seguro para atrasar (como um export), considere enfileirá-lo em vez de bloquear rigidamente, assim usuários reais ainda obtêm resultados.

Projetando quotas por chave que pareçam justas

Quotas por chave costumam ser a abordagem mais justa porque combinam com como os clientes realmente usam seu serviço: uma conta, uma chave de API, responsabilidade clara. Limites baseados em IP ainda são úteis, mas frequentemente penalizam inocentes.

IPs compartilhados são a grande razão. Um escritório inteiro pode sair por um IP público, e operadoras móveis podem colocar milhares de dispositivos atrás de um pequeno pool de IPs. Se você depender apenas de limites por IP, um usuário barulhento pode desacelerar todo mundo. Uma quota por chave evita isso, e você pode manter um pequeno limite por IP como backstop para inundações óbvias.

Para fazer quotas parecerem justas, vincule-as aos planos de cliente sem prender novos usuários. Uma chave gratuita ou de avaliação deve servir para testes reais, apenas não em escala que te prejudique. Um padrão simples é permitir bursts generosos, uma taxa sustentada modesta e uma cota diária que combine com o plano.

Uma política por chave previsível:

• Permitir bursts curtos (loads de página, imports em lote), depois impor uma taxa estável.
• Adicionar um limite diário por chave para limitar scraping e loops descontrolados.
• Aumentar limites por plano, mas manter a mesma estrutura para que o comportamento seja consistente.
• Usar um limite menor para chaves recém-criadas até que ganhem bom histórico.
• Manter um pequeno limite por IP para capturar floods óbvios e clientes mal configurados.

Para desencorajar compartilhamento de chaves e signups automatizados, você não precisa de vigilância pesada. Comece com checagens simples como mudanças geográficas incomuns, muitas IPs distintas por hora para uma chave ou muitas chaves novas criadas da mesma origem. Marque e desacelere primeiro; bloqueie apenas após sinais repetidos.

Tráfego anônimo é onde caps mais rígidos fazem sentido. Se você oferece chaves de avaliação, limite-as fortemente e exija um passo básico de verificação antes de elevar limites. Se sua API alimenta um formulário público, considere um endpoint anônimo separado com sua própria quota para que o resto do backend fique protegido.

Se você constrói sua API com uma plataforma como AppMaster, a lógica por chave é mais fácil de manter consistente porque auth, regras de negócio e tratamento de resposta vivem em um só lugar.

Respostas e headers amigáveis ao cliente (para que usuários possam se recuperar)

A limitação de taxa só funciona a longo prazo se os clientes entenderem o que aconteceu e o que fazer a seguir. Mire em respostas previsíveis: mesmo status code, mesmos campos, mesmo significado entre endpoints.

Quando um cliente atingir um limite, retorne HTTP 429 (Too Many Requests) com uma mensagem clara e um tempo concreto de espera. A vitória mais rápida é adicionar Retry-After, porque até clientes simples podem pausar corretamente.

Um pequeno conjunto de headers torna os limites autoexplicativos. Mantenha nomes consistentes e inclua-os tanto em respostas bem-sucedidas (para que clientes possam se autorregular) quanto em respostas 429 (para que possam se recuperar):

• Retry-After: segundos para esperar antes de retentar
• X-RateLimit-Limit: requisições permitidas na janela atual
• X-RateLimit-Remaining: requisições restantes na janela atual
• X-RateLimit-Reset: quando a janela será resetada (epoch seconds ou ISO time)
• X-RateLimit-Policy: texto curto como "60 requests per 60s"

Faça o corpo de erro tão estruturado quanto suas respostas de sucesso. Um padrão comum é um objeto de erro com um code estável, uma message amigável e dicas de recuperação.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 12 seconds.",
    "retry_after_seconds": 12,
    "limit": 60,
    "remaining": 0,
    "reset_at": "2026-01-25T12:34:56Z"
  }
}

Diga aos clientes como reduzir quando virem 429s. Backoff exponencial é um bom padrão: espere 1s, depois 2s, depois 4s, e coloque um teto (por exemplo, 30–60 segundos). Também seja explícito sobre quando parar de retentar.

Evite surpresas perto das quotas. Quando uma chave estiver próxima do limite (digamos 80–90% usado), inclua um campo ou header de aviso para que clientes possam desacelerar antes de começar a falhar. Isso importa ainda mais quando um script atinge múltiplas rotas rapidamente e consome o orçamento mais depressa do que o esperado.

Passo a passo: um plano simples de rollout para limites e quotas

Um rollout funciona melhor quando você trata limites como um comportamento de produto, não como uma regra de firewall pontual. O objetivo é o mesmo: proteger o backend enquanto mantém clientes normais em movimento.

Comece com um inventário rápido. Liste cada endpoint e marque pelo custo (CPU, trabalho no banco, chamadas a terceiros) e risco (login, password reset, search, upload de arquivos). Isso evita aplicar um limite único a tudo.

Uma ordem de rollout que costuma evitar surpresas:

• Marque endpoints por custo e risco, e decida quais precisam de regras mais estritas (login, bulk export).
• Escolha chaves de identidade por prioridade: chave de API primeiro, depois user id, e IP só como fallback.
• Adicione limites de janela curta (por 10 segundos ou por minuto) para parar bursts e scripts.
• Adicione quotas de janela longa (por hora ou por dia) para limitar uso sustentado.
• Adicione allowlists para sistemas confiáveis e ferramentas internas para que operações não sejam bloqueadas.

Mantenha a primeira versão conservadora. É mais fácil afrouxar depois do que desbloquear usuários zangados.

Monitore e ajuste, depois versione sua política. Acompanhe quantas requisições atingem limites, quais endpoints disparam isso e quantas chaves únicas são afetadas. Quando mudar números, trate como mudança de API: documente, faça rollout gradual e mantenha regras antigas e novas separadas para poder voltar rápido.

Se você constrói sua API com AppMaster, planeje essas regras junto aos endpoints e à lógica de negócio para que os limites reflitam o custo real de cada workflow.

Fluxos de bloqueio que param abuso sem drama

Lockouts são o cinto de segurança. Devem parar abuso óbvio rapidamente, mas ainda dar a usuários normais um caminho claro para se recuperar quando algo dá errado.

Uma abordagem calma é penalidades progressivas. Pressuma que o cliente pode estar mal configurado, não malicioso, e escale apenas se o padrão se repetir.

Uma escada progressiva simples

Use um conjunto pequeno de passos fáceis de explicar e implementar:

• Aviso: informe que o cliente está chegando perto dos limites e quando isso será resetado.
• Desaceleração: adicione atrasos curtos ou limites por segundo mais apertados para aquela chave.
• Bloqueio temporário: bloqueie por minutos (não horas) com horário exato de desbloqueio.
• Bloqueio mais longo: só após surtos repetidos em várias janelas.
• Revisão manual: para padrões que parecem intencionais ou persistem.

Escolher o que bloquear importa. Por chave de API costuma ser mais justo porque mira no chamador, não em todos atrás de uma rede compartilhada. Por conta ajuda quando usuários rotacionam chaves. Por IP pode ajudar com tráfego anônimo, mas causa falsos positivos em NATs, escritórios e operadoras. Quando o abuso é sério, combine sinais (por exemplo, bloqueie a chave e exija checagens extras para aquele IP), mas mantenha o raio de impacto pequeno.

Faça lockouts baseados em tempo com regras simples: "bloqueado até 14:05 UTC" e "reseta após 30 minutos de comportamento bom." Evite bans permanentes para sistemas automatizados. Um cliente com bug pode entrar em loop e queimar limites rápido, então projete penalidades que decaiam com o tempo. Um período sustentado de baixo uso deve reduzir o nível da penalidade.

Se você está construindo sua API no AppMaster, essa escada se mapeia bem para contadores armazenados mais um Business Process que decide permitir, desacelerar ou bloquear e grava o tempo de desbloqueio para a chave.

Para infratores repetidos, mantenha um caminho de revisão manual. Não entre em disputa com usuários. Peça IDs de requisição, timestamps e o nome da chave de API, depois decida com base nas evidências.

Erros comuns que causam falsos positivos

Falsos positivos são quando suas defesas bloqueiam usuários normais. Acontecem quando as regras são simples demais para como as pessoas realmente usam sua API.

Um erro clássico é um limite global para tudo. Se você tratar um endpoint de leitura barato e um export caro da mesma forma, ou você sobreprotege o barato (irritante) ou subprotege o caro (perigoso). Separe limites por custo de endpoint e torne caminhos pesados mais estritos.

A limitação apenas por IP é outra armadilha comum. Muitos usuários reais compartilham um IP público (escritórios, escolas, operadoras móveis). Um usuário pesado pode bloquear todo mundo e parecer uma queda aleatória. Prefira limites primários por chave de API, e use IP como sinal secundário para abuso óbvio.

Falhas também podem criar falsos positivos. Se seu store de limitação cair, "fail closed" pode derrubar toda a API. "Fail open" pode convidar um pico que derruba o backend de qualquer forma. Escolha um fallback claro: mantenha um pequeno cap de emergência na borda e degrade graciosamente em endpoints não críticos.

O tratamento do cliente importa mais do que a maioria das equipes espera. Se você retornar um 429 genérico sem mensagem clara, usuários tentam de novo com força e disparam mais bloqueios. Sempre envie Retry-After e mantenha o texto do erro específico ("Too many requests for this key. Try again in 30 seconds.").

O problema mais evitável é o segredo. Limites escondidos parecem bugs quando clientes chegam a carga de produção pela primeira vez. Compartilhe uma política simples e mantenha-a estável.

Checklist rápido para evitar falsos positivos:

• Separe limites para endpoints caros vs baratos
• Limite primário por chave de API, não só por IP
• Comportamento definido quando o limiter fica indisponível
• Respostas 429 claras com Retry-After
• Limites documentados e comunicados antes da aplicação

Se você constrói sua API com uma ferramenta como AppMaster, isso geralmente significa definir caps diferentes por endpoint e retornar payloads de erro consistentes para que clientes se ajustem sem adivinhação.

Monitoramento e alertas que realmente ajudam

A limitação de taxa só funciona se você consegue ver o que está acontecendo em tempo real. O objetivo não é pegar todo pico. É notar padrões que viram outages ou clientes zangados.

Comece com um conjunto pequeno de sinais que expliquem volume e intenção:

• Requisições por minuto (geral e por chave de API)
• Taxa de 429 (requisições limitadas) e taxa de 5xx (dor no backend)
• Surtos repetidos de 401/403 (chaves ruins, credential stuffing, clientes mal configurados)
• Top endpoints por volume e por custo (queries lentas, exports pesados)
• Endpoints novos ou inesperados aparecendo no top 10

Para separar "tráfego ruim" de "lançamos algo", adicione contexto aos dashboards: horário de deploy, mudanças de feature flag, envios de marketing. Se o tráfego sobe logo após um release e a mistura 429/5xx se mantém saudável, geralmente é crescimento, não abuso. Se o salto está concentrado em uma chave, faixa de IP ou endpoint caro, trate como suspeito.

Alertas devem ser entediantes. Use thresholds mais cooldowns para não ser acordado a cada minuto pelo mesmo evento:

• Taxa de 429 acima de X% por 10 minutos, notificar no máximo uma vez por hora
• 5xx acima de Y% por 5 minutos, pagerar imediatamente
• Uma única chave excede a quota por Z% por 15 minutos, abrir investigação
• Surtos de 401/403 acima de N/min, sinalizar possível abuso

Quando um alerta dispara, mantenha uma nota curta de incidente: o que mudou, o que foi observado (top chaves/endpoints) e o que foi ajustado (limites, caches, bloqueios temporários). Com o tempo, essas notas viram seu playbook real.

Exemplo: você lança um novo endpoint de search e o tráfego dobra. Se a maioria das chamadas atinge esse endpoint em muitas chaves, aumente levemente a quota por chave e otimize o endpoint. Se uma chave atinge exports sem parar e causa latência, limite esse endpoint separadamente e contate o dono.

Checklist rápido: checagens de sanidade antes e depois do lançamento

Uma boa configuração é entediante quando funciona. Esse checklist pega os problemas que geralmente causam falsos positivos ou deixam lacunas óbvias.

Antes de liberar um novo endpoint

Execute essas checagens em staging e novamente logo após o lançamento:

• Identidade: confirme que o limiter usa a chave certa (chave de API primeiro, depois usuário ou IP como fallback) e que chaves rotacionadas não herdam penalidades antigas.
• Limites: defina uma quota padrão por chave, depois ajuste pelo custo do endpoint (leitura barata vs escrita cara) e bursts esperados.
• Respostas: retorne status e informações de recuperação claras (tempo para retry, orçamento restante, código de erro estável).
• Logs: registre quem foi limitado (key/user/IP), qual rota, qual regra disparou e um request ID para suporte.
• Bypass: mantenha uma allowlist de emergência para seus monitores e integrações confiáveis.

Se você constrói no AppMaster, trate cada novo endpoint como uma decisão de tier de custo: um lookup simples pode ser generoso, enquanto qualquer coisa que dispare lógica pesada deve começar mais estrita.

Quando um incidente acontece (abuso ou pico súbito)

Proteja o backend enquanto permite que usuários reais se recuperem:

• Aumente caps temporariamente só para rotas menos arriscadas (frequentemente reads) e monitore as taxas de erro.
• Adicione uma allowlist curta para clientes conhecidos enquanto investiga.
• Apertar rotas específicas arriscadas em vez de reduzir limites globais.
• Ative identidade mais forte (exigir chaves de API, reduzir dependência de IP) para evitar bloquear redes compartilhadas.
• Capture amostras: top chaves, top IPs, user agents e padrões exatos de payload.

Antes de aumentar limites para um cliente, verifique seu padrão normal de requisições, mistura de endpoints e se podem agrupar ou adicionar backoff. Confirme também que não estão compartilhando uma chave entre muitos apps.

Mensalmente, reveja: endpoints mais limitados, porcentagem de tráfego atingindo limites, novos endpoints de alto custo e se suas quotas ainda combinam com o uso real.

Cenário exemplo: proteger uma API pública real sem quebrar usuários

Imagine que você roda uma API pública usada por dois apps: um portal do cliente (alto volume, tráfego estável) e uma ferramenta administrativa interna (baixo volume, mas ações poderosas). Ambos usam chaves de API, e o portal também tem um endpoint de login para usuários finais.

Numa tarde, um parceiro lança uma integração com bug. Ela começa a retentar requisições falhas em loop apertado, enviando 200 requisições por segundo de uma única chave de API. Sem guardrails, essa chave pode expulsar todo mundo.

Limites por chave contêm o raio de impacto. A chave com bug atinge seu cap por minuto, recebe 429 e o resto dos clientes continua trabalhando. Você também pode ter um limite separado, menor, para endpoints caros (como exports) para que mesmo tráfego "permitido" não sobrecarregue o banco.

Ao mesmo tempo, uma tentativa de força bruta começa a martelar o endpoint de auth. Em vez de bloquear a faixa inteira de IP (o que prejudica usuários reais atrás de NAT), você desacelera e depois bloqueia com base no comportamento: muitas tentativas falhas por conta mais limite por IP em uma janela curta. O atacante recebe esperas progressivamente maiores e depois um bloqueio temporário.

Um cliente real que digitou a senha errado algumas vezes pode se recuperar porque suas respostas são claras e previsíveis:

• 429 com Retry-After para que o cliente saiba quando tentar de novo
• Um bloqueio curto (por exemplo, 10–15 minutos), não banimento permanente
• Mensagens de erro consistentes que não vazam se uma conta existe

Para confirmar a correção, você observa algumas métricas:

• Taxa de 429 por chave de API e endpoint
• Taxa de falhas de auth e contagens de lockout
• Latência P95 e CPU do banco durante o incidente
• Número de chaves únicas afetadas (deve ser pequeno)

Isso é o que limitação de taxa protetora parece: ela protege o backend sem punir usuários normais.

Próximos passos: coloque uma política pequena e itere

Você não precisa de um modelo perfeito no dia um. Comece com uma política pequena e clara e melhore à medida que aprende como usuários reais se comportam.

Uma primeira versão sólida costuma ter três partes:

• Uma baseline por chave (requisições por minuto) que cubra a maioria dos endpoints
• Caps mais apertados em endpoints caros (search, exports, uploads, relatórios complexos)
• Respostas 429 claras com uma mensagem curta que diga aos clientes o que fazer a seguir

Adicione lockouts somente onde o risco de abuso é alto e a intenção é fácil de inferir. Signup, login, password reset e criação de tokens são candidatos típicos. Mantenha lockouts curtos no começo (minutos, não dias) e prefira fricção progressiva: desacelere, depois bloqueie temporariamente, depois exija verificação mais forte.

Escreva a política em linguagem simples para que o suporte possa explicar sem precisar de engenharia. Inclua o que é limitado (por chave de API, por IP, por conta), a janela de reset e como o cliente pode se recuperar.

Se estiver implementando isso enquanto constrói um backend novo, AppMaster pode ser um ajuste prático: você cria APIs, define workflows de negócios (incluindo contadores e decisões de lockout) visualmente, depois faz deploy em provedores de nuvem ou exporta o código gerado quando precisar de controle total.