Um limite de consumo protege uma API contra picos, erros de integração e utilizações que podem degradar o serviço. Também condiciona a experiência de quem depende dela: uma política demasiado restritiva pode interromper processos legítimos, enquanto uma política demasiado permissiva deixa pouca margem de reação perante uma sobrecarga.
A decisão não consiste em escolher um número universal de pedidos por minuto. Consiste em identificar o recurso que se pretende proteger, compreender os padrões normais e tornar o limite claro e previsível. Este guia apresenta critérios para definir quotas, responder a excessos e rever a política com base em dados.
Que problemas resolvem os limites e o que não substituem
Os limites controlam o consumo de um cliente ou processo durante um intervalo, ou quantas operações simultâneas pode manter. Ajudam a distribuir a capacidade, conter picos e reduzir o impacto de erros, como um ciclo que repete chamadas sem pausa. Também podem apoiar uma oferta comercial com níveis de utilização definidos.
No entanto, uma quota não substitui o planeamento de capacidade, a proteção contra ataques nem a conceção eficiente da API. Um limite pode reduzir a pressão, mas não corrige uma consulta dispendiosa, uma dependência lenta nem uma estratégia de novas tentativas mal concebida. Também não garante, por si só, que todos os consumidores recebam uma parte equitativa dos recursos.
Antes de definir um limite, clarifique o objetivo: pretende proteger uma operação dispendiosa, reservar capacidade para diferentes clientes ou estabelecer uma condição do serviço? Se houver vários objetivos, separe-os. As políticas técnicas de proteção e as regras comerciais podem coincidir, mas não devem ser confundidas: têm critérios de alteração e necessidades de comunicação diferentes.
Identifique os consumidores e as operações antes de definir valores
Uma quota só é útil se o sistema conseguir associar os pedidos a uma identidade estável. Determine se o consumidor é uma conta, uma aplicação registada, uma credencial, uma equipa interna ou um utilizador final. Um endereço IP pode fornecer um sinal adicional, mas nem sempre identifica um cliente: várias pessoas podem partilhá-lo e o mesmo cliente pode alterá-lo.
Em seguida, classifique as operações. Ler um recurso em cache normalmente não tem o mesmo custo que gerar um relatório, iniciar uma exportação ou executar uma pesquisa ampla. Agrupar todos os endpoints num único limite simplifica a explicação, mas pode tratar de forma desigual chamadas com custos muito diferentes.
Analise o tráfego real e os cenários esperados antes de estabelecer valores. Procure padrões por consumidor, endpoint, hora, duração dos pedidos, simultaneidade e erros. Verifique também que integrações processam lotes ou fazem sincronizações periódicas. Uma integração legítima pode concentrar chamadas numa janela breve sem se comportar como tráfego contínuo.
- Por conta ou aplicação: facilita uma política estável para o cliente, desde que a identidade esteja corretamente associada.
- Por operação: permite proteger funções com custos ou capacidades diferentes.
- Por recurso partilhado: ajuda a conter a pressão sobre uma base de dados, um fornecedor ou um processo comum.
O âmbito escolhido deve corresponder ao recurso protegido. Se for possível contornar um limite por credencial criando novas credenciais, talvez a conta seja a unidade adequada. Se uma operação partilhar um recurso com outros endpoints, uma quota individual pode não ser suficiente para o proteger.
Quotas, simultaneidade e picos: escolha o controlo adequado
Uma quota limita o volume de pedidos num determinado período. É útil para expressar um orçamento de consumo e é fácil de comunicar, mas é necessário definir com clareza o intervalo e o que conta como pedido. Uma janela fixa pode permitir uma concentração de tráfego perto da mudança de período; uma janela móvel ou um sistema baseado em tokens pode suavizar esse efeito, mas acrescenta complexidade à implementação e à explicação.
O limite de simultaneidade restringe o número de operações que podem estar ativas ao mesmo tempo. É útil quando os pedidos são longos ou consomem recursos durante a execução. Não limita necessariamente o volume total: um cliente pode concluir muitas operações pequenas, uma após outra. Por isso, pode ser combinado com uma quota quando ambos os riscos são relevantes.
O controlo de picos permite absorver um aumento breve sem aceitar um ritmo elevado indefinidamente. É adequado para sincronizações ou para o arranque de processos, desde que o serviço consiga suportar esse pico. Não convém permitir picos apenas porque o tráfego médio parece baixo: a capacidade disponível durante o pico também é importante.
Para escolher, pergunte o que se esgota primeiro: o orçamento de trabalho acumulado, o número de operações simultâneas ou a capacidade instantânea. Utilize o controlo mais simples que proteja contra o risco observado. Combinar mecanismos sem uma razão clara pode gerar limites difíceis de diagnosticar e mensagens contraditórias.
Responda aos excessos de forma previsível
Quando o consumidor ultrapassa um limite temporário, a resposta de rejeição deve distinguir-se de uma falha inesperada do serviço. Em muitos casos, o código HTTP 429 indica que foram recebidos demasiados pedidos num determinado período. Se o sistema conseguir estimar quando poderá aceitar outro pedido, pode comunicar essa informação através do cabeçalho Retry-After. A resposta também deve explicar que limite foi atingido e onde consultar a política aplicável.
Não prometa um prazo de recuperação que o sistema não possa garantir. Se não for possível indicar quando haverá capacidade disponível, evite sugerir novas tentativas imediatas. Os clientes devem aplicar uma espera progressiva, limitar as tentativas e, quando adequado, acrescentar uma variação aleatória ao tempo de espera para evitar que todos tentem novamente ao mesmo tempo.
Se o pedido iniciar uma operação dispendiosa ou não idempotente, especifique como tratar uma rejeição e se é seguro voltar a enviar o pedido. Um cliente não deve interpretar qualquer erro como autorização para repetir uma operação sem limite. Documente também as diferenças entre uma quota esgotada, uma credencial inválida e uma indisponibilidade temporária.
Conceba exceções transparentes e sujeitas a revisão
Pode haver motivos legítimos para ajustar uma quota: uma migração, uma sincronização acordada ou uma alteração comprovada no padrão de utilização. Defina quem pode pedir a exceção, de que informação precisa, quem a aprova e quando será revista. Registe o âmbito, a duração e o responsável, para que a exceção não se torne uma regra permanente por inércia.
Evite exceções informais associadas a uma pessoa específica ou a acordos desconhecidos pela equipa operacional. Se a alteração responder a uma condição comercial, coordene a comunicação entre produto, negócio e tecnologia. Se responder a uma necessidade técnica temporária, esclareça o critério para a retirar.
As quotas podem mudar, mas o processo não deve surpreender as integrações ativas. Comunique antecipadamente as alterações relevantes, indique quem será afetado e disponibilize uma via de migração quando possível. Publique os limites atuais e explique se são valores garantidos ou limiares sujeitos a revisão. A transparência sobre as alterações faz parte da política, não é um pormenor administrativo.
Reveja as métricas sem incentivar novas tentativas abusivas
Acompanhe tanto o consumo aceite como os pedidos rejeitados. Analise os dados por consumidor e operação e relacione-os com a latência, os erros, a simultaneidade e a pressão sobre as dependências. Um aumento das respostas 429 pode indicar abuso, mas também uma quota mal calibrada, uma alteração no produto ou uma integração que não recebeu a comunicação adequada.
Interprete os sinais em conjunto. Se um cliente atingir ocasionalmente o limite durante uma tarefa prevista e ainda houver capacidade disponível, talvez a política de picos ou o intervalo não correspondam ao seu padrão. Se vários consumidores aumentarem simultaneamente a latência e a saturação de uma dependência, aumentar as quotas pode agravar o problema.
Conte e analise as novas tentativas: muitos pedidos rejeitados podem inflacionar o tráfego e ocultar a procura real de trabalho. Procure sequências repetidas sem espera, concentrações logo após o reinício de uma janela e chamadas falhadas repetidas sem alterações. Partilhe estas conclusões com o consumidor sempre que possível e avalie o efeito de cada ajuste antes de o alargar a todos.
Lista de verificação para publicar uma política
- Defina o recurso ou risco que cada limite protege.
- Identifique o consumidor através de uma chave estável e explique como as respetivas credenciais são agrupadas.
- Separe as operações quando os custos ou padrões de utilização forem diferentes.
- Especifique a unidade, o período, o âmbito, a simultaneidade e o comportamento perante picos.
- Documente a resposta ao excesso e as instruções para novas tentativas.
- Estabeleça um processo auditável para exceções e alterações.
- Monitorize rejeições, novas tentativas, latência e pressão sobre os recursos.
- Reveja a política com base em dados e, sempre que viável, comunique as alterações antes de as aplicar.
A melhor política não é a que maximiza o número de chamadas permitido, mas a que protege o serviço sem tornar a utilização imprevisível para clientes e equipas internas. Comece pelo risco concreto, aplique limites compreensíveis e ajuste-os apenas quando as métricas e os padrões de integração justificarem a decisão.