Jitter nas retentativas de requisição

O que é jitter nas retentativas de requisição?

Quando um sistema chama uma API e a resposta falha, por exemplo por instabilidade momentânea, tempo esgotado ou excesso de requisições, o comportamento comum é tentar de novo depois de alguns segundos. Essa nova tentativa é chamada de retentativa (ou retry).

Jitter é o ingrediente de aleatoriedade colocado nesse tempo de espera. Em vez de esperar exatamente 2 segundos, o sistema espera um valor sorteado, como 1,3 ou 1,8 segundo. A palavra vem do inglês e significa algo como tremulação ou oscilação.

Por que o jitter é necessário?

Imagine centenas de sistemas emitindo notas fiscais ao mesmo tempo. Se o serviço fica fora do ar por alguns segundos, todos recebem erro quase no mesmo momento. Se todos usam a mesma regra de espera fixa, todos voltam a tentar exatamente juntos, criando uma nova onda de tráfego que pode derrubar o serviço outra vez.

Esse efeito é conhecido como efeito manada (thundering herd, em inglês). O jitter quebra essa sincronia: cada cliente volta em um momento diferente, o tráfego chega de forma mais distribuída e o serviço consegue se recuperar e atender as requisições aos poucos.

Como o jitter funciona junto com o backoff exponencial?

O backoff exponencial define que o tempo de espera cresce a cada falha: por exemplo, 1, 2, 4, 8 segundos. Ele evita que o cliente insista sem parar, mas sozinho ainda mantém os clientes sincronizados, porque todos seguem a mesma sequência.

O jitter entra sorteando um valor dentro desse intervalo. Uma abordagem comum é sortear qualquer valor entre zero e o tempo calculado pelo backoff (chamada de jitter completo). Outra é manter metade do tempo fixa e sortear a outra metade, garantindo uma espera mínima. Em ambos os casos, costuma-se definir também um tempo máximo de espera e um número máximo de tentativas.

Qual a diferença entre backoff exponencial e jitter?

O backoff exponencial responde à pergunta quanto tempo, em média, devo esperar antes de tentar de novo, aumentando o intervalo a cada falha. O jitter responde à pergunta como evitar que todo mundo espere exatamente o mesmo tempo, adicionando aleatoriedade.

São técnicas complementares e quase sempre usadas juntas. Backoff sem jitter ainda gera picos sincronizados; jitter sem backoff espalha as tentativas, mas não reduz a pressão sobre um serviço que continua com problema.

Quando usar jitter na emissão fiscal por API?

Na integração fiscal, o jitter é útil sempre que uma falha é provavelmente passageira: respostas HTTP 429 (limite de requisições atingido), erros 5xx do servidor, tempo esgotado na conexão ou indisponibilidade temporária de serviços como SEFAZ e prefeituras.

Ele não deve ser usado para erros que não vão se resolver sozinhos, como rejeições de validação fiscal, CFOP incorreto, certificado vencido ou dados de destinatário inválidos. Nesses casos, tentar de novo apenas repete o mesmo erro; o correto é corrigir o dado e reenviar.

Que cuidados tomar ao repetir uma emissão de nota fiscal?

O maior risco de repetir uma requisição de emissão é gerar documentos em duplicidade. Se a primeira tentativa chegou ao servidor, mas a resposta se perdeu no caminho, uma nova tentativa pode criar uma segunda nota. Por isso, retentativas devem ser combinadas com idempotência, usando um identificador único por operação para que o servidor reconheça repetições.

Também vale respeitar o cabeçalho Retry-After quando a API informa quanto tempo esperar, registrar cada tentativa em log para auditoria e preferir fluxos assíncronos com fila, consultando o status do documento em vez de reenviar repetidamente.

Exemplos de Jitter nas retentativas de requisição

• Um ERP envia 500 NF-e no fechamento do dia e recebe HTTP 429. Em vez de reenviar todas após exatamente 5 segundos, cada requisição espera um tempo sorteado entre 0 e 5 segundos, depois entre 0 e 10, e assim por diante, até o limite de tentativas.
• Uma plataforma de e-commerce tem uma falha de conexão ao emitir NFC-e. O código aplica backoff exponencial com jitter e envia sempre a mesma chave de idempotência, garantindo que, se a primeira tentativa tiver sido processada, nenhuma nota duplicada seja gerada.
• Um marketplace que emite NFS-e para vários municípios detecta lentidão no serviço de uma prefeitura. As retentativas com jitter distribuem os reenvios ao longo de alguns minutos, evitando sobrecarregar ainda mais o serviço municipal durante a recuperação.
• Um agente de inteligência artificial que consulta o status de documentos via MCP recebe erro temporário e aguarda um intervalo aleatório antes de consultar de novo, em vez de repetir a chamada imediatamente em sequência.