Limites de API: controle a cadência da integração

Uma integração pode enviar requisições corretas e ainda assim parar de funcionar quando vários processos usam a mesma API ao mesmo tempo. Importações, consultas e atualizações disputam capacidade. Se cada processo responder a uma recusa criando mais tentativas imediatas, o trabalho aumenta justamente quando deveria desacelerar. O controle de cadência precisa existir antes da primeira falha e abranger todos os consumidores que compartilham o mesmo limite.

Descubra qual limite está em jogo

Reúna a documentação do fornecedor e registre como a cota é calculada: por conta, credencial, recurso, endpoint ou outra unidade. Diferencie taxa de envio, volume em uma janela e número de operações simultâneas. Um limite de concorrência não é automaticamente um limite por minuto. Também confirme se consultas e escritas usam a mesma capacidade e quais sinais aparecem nas respostas.

O código 429 Too Many Requests indica excesso de requisições em determinado intervalo. A RFC 6585 permite que a resposta inclua Retry-After, mas não obriga sua presença. Pela semântica HTTP desse cabeçalho, o valor pode ser uma data ou um intervalo em segundos. A implementação precisa interpretar o formato recebido, sem presumir uma única representação.

Coloque uma fila antes do envio

No roteiro proposto, cada trabalho entra em uma fila com identificador, operação, prioridade, estado e próxima tentativa permitida. Um controlador decide o que pode sair naquele momento. Assim, quem produz trabalho não determina diretamente a taxa das chamadas. O mesmo controle deve considerar outros processos que compartilham a credencial; limitar apenas um serviço pode deixar o conjunto acima da capacidade.

Não preencha a ficha com números copiados de outro sistema. Comece pelos valores documentados e pela capacidade contratada. Quando o fornecedor não expõe uma cota fixa, use um ritmo conservador, observe respostas e mantenha um canal para esclarecer o comportamento. O controle deve permitir ajuste sem exigir que o operador altere código durante um incidente.

Exemplo fictício de recusa

Imagine três trabalhadores consumindo uma fila comum. O primeiro recebe 429 com uma espera indicada. Se o limite é compartilhado, reduzir apenas esse trabalhador pode não resolver: os outros continuam enviando chamadas. O controlador registra a restrição para o grupo correto e mantém os itens aguardando. Depois do intervalo, retoma gradualmente, observando se a pressão sobre o serviço diminuiu.

Se o cabeçalho não vier, aplique a política documentada de retentativa, com atraso progressivo, variação e limite de tentativas. Não trate todo erro como problema de taxa: uma credencial inválida ou um corpo malformado exige outra ação. Para escritas, considere que uma interrupção de rede pode deixar o resultado desconhecido; repetir uma operação precisa respeitar a estratégia de idempotência ou de consulta do estado.

Meça espera e resultado

Conte requisições iniciadas, recusadas e concluídas por endpoint e grupo de credencial, sem registrar o segredo. Acompanhe também a idade do item mais antigo e a quantidade de trabalho pendente. Uma taxa baixa de erros pode esconder uma fila que nunca termina. Separe tempo gasto esperando autorização de envio do tempo de resposta do fornecedor, porque as ações corretivas são diferentes.

Ensaie um pico controlado

1. Use ambiente de teste ou simulador que reproduza respostas 429 sem pressionar produção.
2. Dispare mais trabalho do que o controlador permite enviar simultaneamente.
3. Confira se a fila cresce de modo visível e se a concorrência permanece limitada.
4. Teste respostas com segundos, data e ausência de Retry-After.
5. Verifique a retomada e confirme que operações não foram perdidas ou aplicadas duas vezes.

Registre os resultados na política de retentativas e fila de falhas. Relacione a cadência à sincronização por lotes e ao contrato da integração. A implementação depende das garantias oferecidas por cada API, não de uma promessa universal de capacidade.