Limites e throttling de API: como não esbarrar neles

Uma integração que funcionava perfeitamente no teste com uma dezena de requisições começa a receber recusas sob carga real. O problema não é uma falha da API: o ritmo das requisições simplesmente passou do limite permitido. Vamos entender por que os limites existem, como diferenciá-los de uma falha do serviço, como suavizar a carga do seu lado e por que consultar o status a cada segundo geralmente não acelera o resultado.

Por que os serviços limitam a frequência de requisições

O limite protege a infraestrutura compartilhada: sem restrição, um único cliente com um script agressivo pode ocupar recursos de que todos os outros precisam. Também é uma divisão justa da capacidade — o limite por conta garante que a integração de outra pessoa não consuma a largura de banda que você pagou. Bater nesse limite tem um sinal concreto: o serviço responde com o código 429 e, muitas vezes, anexa um cabeçalho com a pausa recomendada antes de tentar de novo. Isso é bem diferente de uma falha do serviço — numa falha, todos os clientes recebem erro, em operações variadas, enquanto o throttling é direcionado justamente à sua chave e ao ritmo das suas requisições. Se a resposta traz um código claro de limitação, a infraestrutura está de pé e funcionando normalmente — o problema é a velocidade com que você bate à porta, não o serviço.

Ritmo constante em vez de picos

Muitos limites são contados por janela de tempo — um segundo ou um minuto. Se você enviar cem requisições de uma só vez e depois ficar parado, o contador da janela se esgota instantaneamente, embora a carga média ao longo da hora possa ser modesta. A restrição reage ao pico, não à média. O mesmo volume de trabalho, distribuído de forma uniforme dentro da janela, passa sem nenhuma recusa. Suavizar o ritmo não significa fazer menos requisições, e sim não concentrá-las num intervalo estreito.

Fila e limite de fluxos paralelos do seu lado

As tarefas de um aplicativo raramente surgem de forma uniforme: um lote inteiro de trabalho pode chegar de uma vez — por exemplo, depois de uma importação de dados ou de uma operação em massa do usuário. Se cada tarefa gera imediatamente uma requisição à API, o pico do seu lado vira um pico na fronteira do serviço. Uma fila com velocidade de saída controlada resolve esse descompasso: as tarefas se acumulam na fila, e para fora sai um fluxo regular de requisições. Além disso, vale limitar o número de conexões paralelas com a API — mesmo com fila, dez fluxos batendo ao mesmo tempo num endpoint com limite de frequência criam o mesmo pico que um único fluxo sem controle.

Consulta de status e pausa após a recusa

Consultar o status de uma operação a cada segundo quase sempre é excessivo: o resultado não aparece mais rápido só porque você perguntou com mais frequência. Uma operação real — entrega de SMS, criação de uma porta, processamento de um pagamento — é limitada pela rede e pela fila interna do próprio serviço, e consultar com mais frequência do que esse tempo natural apenas queima a cota sem aproximar a resposta. Um intervalo de consulta razoável parte do tempo típico de execução da operação, e não da vontade de ver o resultado instantaneamente.

Ao receber uma recusa por limite, não repita a requisição imediatamente no mesmo ritmo — isso prolonga o bloqueio com certeza. A reação correta é a pausa exponencial: cada nova tentativa espera mais que a anterior, por exemplo um segundo, depois dois, quatro, oito. Se o serviço devolveu um cabeçalho com o tempo de espera recomendado, guie-se por ele, e não pelo seu palpite.

Limites separados por chave e monitoramento do limite

O limite quase sempre está vinculado a uma chave ou conta, e não ao serviço como um todo. Se a sincronização em segundo plano e o fluxo do usuário usam a mesma chave de API, uma tarefa pesada em segundo plano pode consumir toda a cota e deixar o usuário comum sem resposta. Chaves diferentes para tarefas diferentes dão contadores diferentes — exatamente o mesmo princípio de separação que vale para a API de proxy. Também vale acompanhar o consumo da cota de forma proativa: muitas APIs devolvem na resposta o saldo restante, e é por ele que, na área do cliente, dá para ver a aproximação do limite antes de as recusas começarem, e não depois do primeiro 429.

Perguntas frequentes

É possível aumentar o limite para uma conta específica?

Em alguns serviços, o limite cresce junto com o plano ou mediante um pedido separado ao suporte, descrevendo o cenário de carga. Não vale contar com isso de antemão — o certo é projetar a integração para o limite atual e tratar a ampliação como bônus, não como plano.

Por que o 429 aparece mesmo com um ritmo baixo de requisições?

Uma causa frequente é uma chave compartilhada com outro processo que já consome parte da cota. Outra é que a janela do limite é mais curta do que parece: o ritmo médio por minuto é baixo, mas dentro de um segundo acontecem picos. Vale verificar as duas hipóteses antes de mudar a lógica da própria integração.

O limite é o mesmo para todos os métodos da API?

Geralmente não: operações pesadas, como buscas ou consultas em massa, são limitadas com mais rigor do que uma simples verificação de status. O correto é se guiar pela tabela de limites de cada método na documentação, e não por um único número geral.

Os valores exatos dos limites, os códigos de erro e os cabeçalhos com a pausa antes de tentar de novo estão na documentação da OTP API.