Como economizar chamadas de API: o que consome sem você perceber

Quase toda integração que estoura o limite de chamadas faz isso pelo mesmo motivo: ela pergunta muitas vezes a mesma coisa. Não é volume de trabalho de verdade — é repetição. E como o efeito só aparece quando o teto é atingido, a primeira notícia costuma ser a pior possível: o sistema simplesmente para de responder, no meio do expediente, sem que ninguém tenha mudado nada.

Este guia é sobre os quatro hábitos que consomem chamadas sem entregar nada em troca, e o que colocar no lugar de cada um. Vale para qualquer integração com API — não só a nossa.

1. Perguntar de novo o que não mudou

O padrão mais comum: um agendamento roda de minuto em minuto e relê o mesmo item, esperando que algo tenha mudado. Na prática, um processo pode passar semanas sem movimento novo, e uma publicação, depois de publicada, não muda mais. Cada releitura é uma chamada gasta para receber exatamente a mesma resposta.

No lugar disso: guarde a resposta do seu lado e só volte a perguntar quando fizer sentido. Se o dado é imutável — o teor de uma publicação, por exemplo —, leia uma vez e guarde o ETag que veio na resposta: relendo com If-None-Match, o motor confirma que nada mudou sem retransmitir o ato inteiro. Se o dado muda de vez em quando, defina um intervalo compatível com a realidade dele: um processo consultado uma vez por dia já é mais frequente do que a maior parte deles se movimenta.

2. Ficar perguntando em vez de ser avisado

Perguntar repetidamente “já mudou?” é o método mais caro de descobrir uma novidade, e o mais lento: entre a mudança e a próxima pergunta há sempre uma espera. É o oposto do que se quer quando o assunto é prazo.

No lugar disso: use notificação. Você cadastra o que quer acompanhar — um processo, uma inscrição na OAB, um nome de parte, um termo — e o motor varre as edições novas sozinho. Se você tem um endereço público para receber, o aviso chega assinado no seu servidor; se não tem, o mesmo incremental fica disponível para buscar, numa chamada que pede o que apareceu desde a última vez. Some-se o efeito prático: a varredura e o aviso não custam crédito nenhum — você paga pelas consultas que faz, não pela vigilância que o motor mantém —, e você fica sabendo no momento em que acontece, não no próximo ciclo do seu agendamento.

3. Pedir item por item o que cabe em uma página

Outro desperdício silencioso é buscar uma lista e depois abrir cada resultado individualmente para pegar um detalhe que a própria lista já trazia. Vinte resultados viram vinte e uma chamadas onde uma bastaria.

No lugar disso: antes de escrever o laço, olhe o que a resposta da lista já contém. Numa busca de publicações, o teor do ato já vem junto — não é resumo, é o texto inteiro; se ele for grande demais para o seu caso, peça um recorte em vez de abrir cada item depois. E quando o que você quer é o retrato de um processo, existe a chamada que devolve cadastro e movimentações de uma vez, com uma versão em lote que faz o mesmo para vários números.

4. Repetir a chamada que falhou, na mesma hora

Quando uma chamada falha, a reação automática é tentar de novo imediatamente. Se a causa foi justamente um limite atingido, a retentativa imediata só piora: cada tentativa mantém o teto ocupado e adia a recuperação.

No lugar disso: espere antes de repetir, e espere mais a cada nova falha. Respostas de limite costumam trazer um cabeçalho Retry-After dizendo em quantos segundos vale tentar de novo — é a resposta te dando a instrução exata. Respeitá-la resolve o caso sem nenhuma adivinhação.

Como saber onde está indo o seu consumo

Antes de ampliar qualquer plano, vale olhar o extrato: quais chamadas você mais faz, quanto cada tipo custou no ciclo e quantas foram servidas do acervo em vez de irem à fonte — essa última proporção é a medida direta da repetição. O extrato é uma consulta de custo zero, aparece pronto no painel da conta e também pode ser perguntado ao seu assistente de IA. Costuma ser desconfortável: a maior parte do consumo tende a estar concentrada em um punhado de rotinas automáticas que ninguém revisita desde o dia em que foram escritas.

A conta é simples de fazer: se uma rotina roda a cada minuto, são mais de mil e quatrocentas chamadas por dia; passando para uma vez por hora, são vinte e quatro. Na esmagadora maioria dos casos jurídicos, a segunda frequência entrega exatamente a mesma informação útil que a primeira.

Vale entender qual teto cada chamada ocupa, porque são dois e eles contam coisas diferentes: a vazão por minuto conta toda requisição, enquanto o teto do dia conta apenas as que vão até a fonte — ler o que já está no acervo não o consome. Os números de cada plano e o tratamento certo de cada recusa estão em limites e cotas.

O resumo

• Guarde o que já leu. Dado que não muda não precisa ser perguntado duas vezes.
• Prefira ser avisado a ficar perguntando. É mais barato e chega antes.
• Aproveite a lista. Ela quase sempre já traz o que você ia buscar item a item.
• Recue depois de falhar. A recusa por limite não é um “não” seco: ela vem com o Retry-After e com os campos que dizem qual teto foi atingido e quando ele reabre. Respeitar esses valores resolve o caso sem adivinhação, e há um exemplo de retentativa pronto em limites e cotas.

Nenhuma dessas mudanças exige reescrever a integração. Todas as quatro costumam caber em um dia de trabalho — e o efeito aparece já no dia seguinte, no consumo que deixou de acontecer.