Leonardo Peron5 min de leitura
Existe um momento previsível na vida de toda integração: ela funciona bem no teste, funciona bem na primeira semana, e quebra no dia em que o volume dobra. A mensagem que aparece costuma ser um código 429 — too many requests — e o que ela quer dizer é simples: o fornecedor decidiu quantas chamadas você pode fazer, e você passou.
Quase todo ERP, marketplace e gateway impõe esse limite. Ele raramente aparece no começo do manual, e nunca aparece na conversa comercial.
Descubra o limite real antes de precisar dele
A documentação diz um número. O comportamento em produção costuma dizer outro, por três motivos:
O limite pode ser por conta, não por integração. Se a mesma credencial é usada pela integração da loja, pelo BI e por um relatório que alguém agendou, os três dividem a mesma cota. A sua integração recebe 429 por causa de um comportamento que não é dela.
A janela pode não ser a que você imagina. "Cem chamadas por minuto" pode significar cem em qualquer janela de sessenta segundos, o que é bem mais restritivo que cem por minuto de relógio. Vinte chamadas às 10h00m59s e mais oitenta às 10h01m01s estouram um limite deslizante e passam num limite por minuto cheio.
Pode haver mais de um limite ao mesmo tempo. Por segundo, por minuto, por dia, e às vezes um limite separado por tipo de operação — consulta é barata, criação é cara.
Vale medir em vez de acreditar: dispare chamadas em ritmo crescente contra o ambiente de homologação e anote onde o 429 aparece. Meia hora de teste evita semanas de comportamento inexplicável.
O 429 traz a resposta junto
Quando o limite estoura, a maioria dos fornecedores devolve um cabeçalho
dizendo quanto tempo esperar — normalmente Retry-After. É a informação mais
útil da resposta inteira, e é a que quase toda integração ignora.
Respeitar esse valor resolve o caso sozinho na maior parte das vezes. Ignorar e tentar de novo imediatamente produz o efeito oposto: mais 429, e em alguns fornecedores um bloqueio temporário mais longo, aplicado justamente a quem insiste.
Quando o cabeçalho não vem, vale o mesmo recuo exponencial de qualquer falha temporária: espera crescente até um teto.
Não peça o que você já tem
A forma mais barata de caber no limite é fazer menos chamadas. Três hábitos cortam a maior parte do volume:
Pergunte só o que mudou. Boa parte das integrações varre o catálogo inteiro a cada rodada porque foi assim que começou. Se a API aceita filtro por data de alteração, sincronizar só o que mudou desde a última execução costuma reduzir o volume em uma ordem de grandeza.
Use o lote quando ele existir. Muitos fornecedores aceitam consultar cinquenta itens numa chamada só. Cinquenta chamadas individuais e uma chamada em lote entregam o mesmo dado e consomem cotas muito diferentes.
Guarde o que não muda. Tabela de estados, lista de transportadoras, categorias de produto — dado que muda uma vez por semestre não precisa ser consultado a cada pedido processado.
Controle o ritmo de dentro
Descobrir o limite não adianta se a integração continua disparando no ritmo que der. É preciso um freio do lado de cá — um componente por onde toda chamada passa e que segura quando o ritmo se aproxima do teto.
Duas escolhas importam mais que a implementação:
Fique abaixo do limite, não nele. Trabalhar a noventa por cento do teto dá margem para o pico e para as chamadas que você não controla. Colar no limite transforma qualquer variação em erro.
O freio é por credencial, não por processo. Se dois processos usam a mesma conta, um freio em cada um deles soma o dobro do permitido. O controle precisa ficar onde a cota é contada.
Nem tudo tem a mesma pressa
Quando a cota é escassa, ela vira um recurso a ser distribuído — e distribuir por ordem de chegada é quase sempre a pior escolha.
Um pedido pago esperando para entrar no ERP e uma sincronização de catálogo disputando a mesma cota não têm o mesmo peso. O pedido tem cliente do outro lado; o catálogo pode terminar meia hora depois sem que ninguém perceba.
Separar em duas filas com prioridades diferentes resolve, e o efeito prático é grande: no dia em que a cota apertar, o que trava é o que pode esperar.
O corolário vale registrar: rotina pesada não roda em horário de pico. Recarga completa de catálogo, exportação de histórico e recálculo de estoque cabem na madrugada, quando a cota está ociosa.
O limite vai mudar sem aviso
Fornecedor muda política de limite, e raramente avisa com antecedência
suficiente. Integração que trata 429 como caso excepcional quebra nesse dia.
Integração que trata como condição normal — respeita o Retry-After, recua,
prioriza, alerta — desacelera e continua entregando.
A diferença entre as duas não é sofisticação. É ter decidido, antes, que o limite existe.
O teste que confirma
Baixe o teto do seu próprio freio para um valor absurdamente pequeno — cinco chamadas por minuto — e deixe a integração processar um lote de cem eventos.
O comportamento correto é ficar lenta e terminar tudo, na ordem de prioridade certa, sem perder nenhum evento e sem duplicar nenhum. Se em vez disso ela falhar, pular itens ou empilhar erro, o problema não é o limite do fornecedor: é o desenho, e ele ia aparecer de qualquer forma no primeiro pico de verdade.