# Timeout e retry policies em HTTP: guia prático > Timeout e retry policies em HTTP são estratégias essenciais para sistemas resilientes. O guia prático apresenta configuração de timeouts por conexão e resposta, além de retries com backoff exponencial e jitter. A implementação correta evita sobrecarga de servidores e falhas em cascata. O conteúdo aborda erros comuns, como retries em requisições não idempotentes, e recomenda monitoramento ativo para ajustar políticas conforme a latência observada. *PosUp · Apps e Software · 31 de agosto de 2026 · Patrícia Lemos* Implementar timeout e retry policies em chamadas HTTP é essencial para sistemas resilientes. Este guia mostra o passo a passo, com dicas para evitar erros comuns e melhorar a confiabilidade das suas integrações. Quando uma chamada HTTP falha, a primeira reação é tentar de novo. Mas repetir sem critério pode derrubar o serviço que já está lento. Timeout e retry policies bem definidos são o que separa uma integração frágil de uma que aguenta picos de instabilidade. Este guia mostra como implementar esses mecanismos na prática, com etapas claras e erros comuns que você vai querer evitar. ## Passo 1: Defina timeouts curtos e específicos por chamada O timeout é o tempo máximo que você espera por uma resposta. Sem ele, uma chamada lenta segura um thread, uma conexão e a paciência do usuário. A regra geral: use timeouts curtos e direcionados, não um valor global para tudo. Uma chamada que busca um produto no catálogo não deveria esperar 60 segundos. Algo em torno de 2 a 5 segundos costuma ser razoável para operações simples. Para operações mais pesadas, como relatórios ou exportações, você pode esticar para 30 segundos, mas nunca acima de 60 segundos, como recomendado na documentação de APIs de grandes plataformas, como a commercetools. **Erro comum a evitar:** aplicar o mesmo timeout para todas as chamadas. Uma operação de leitura leve e uma de escrita pesada têm perfis diferentes. Se o timeout for curto demais para a operação pesada, você corta respostas válidas. Se for longo demais para a leve, acumula latência desnecessária. **Dica:** meça o percentil 95 e 99 do tempo de resposta normal das suas chamadas. O timeout deve ficar acima desses valores, com uma margem de segurança, mas não muito acima. ## Passo 2: Identifique quando o retry realmente ajuda Retry é para erros transitórios, não para erros permanentes. Um erro 500 de servidor pode ser temporário, um 503 de indisponibilidade também. Mas um 400 (requisição inválida) ou 401 (não autorizado) não vai se resolver com uma nova tentativa, porque o problema está no seu lado ou na autenticação. A lógica é simples: se o erro indica que a requisição está errada, corrigir o código, não repetir a chamada. Se o erro é do servidor ou da rede, uma nova tentativa pode funcionar. **Erro comum a evitar:** fazer retry para todos os códigos HTTP. Isso amplifica a carga no servidor em momentos de falha e pode transformar uma indisponibilidade pontual em uma cascata de requisições. **Dica:** monte uma lista explícita de códigos que merecem retry. Em geral, 408 (timeout), 429 (muitas requisições), 500, 502, 503 e 504 são bons candidatos. Para os demais, falhe rápido. ## Passo 3: Configure um número máximo de tentativas Não existe retry infinito. Cada tentativa adicional aumenta a chance de sucesso, mas também aumenta a carga e o tempo total de espera. O ponto de equilíbrio costuma estar entre 2 e 5 tentativas no total. Se a primeira chamada falhou, uma segunda tentativa imediata pode resolver um problema de rede. Uma terceira, com um pequeno atraso, resolve um servidor que estava reiniciando. Mais do que isso, você provavelmente está tentando forçar uma integração que precisa de intervenção manual. **Erro comum a evitar:** usar o mesmo número de tentativas para todos os cenários. Uma chamada de pagamento pode exigir menos tentativas, para não duplicar transações. Uma consulta de status pode tolerar mais, porque é idempotente. **Dica:** para operações não idempotentes, como criação de recursos, prefira retries com cuidado. Se a primeira tentativa criou o recurso e a resposta se perdeu, o retry pode criar um duplicado. Nesses casos, considere usar um identificador de idempotência na requisição. ## Passo 4: Use backoff exponencial com jitter Se todas as tentativas acontecem ao mesmo tempo, você cria um pico de requisições sincronizadas. O backoff exponencial resolve isso: cada nova tentativa espera um tempo maior que a anterior, como 1 segundo, depois 2, depois 4. O jitter, que é uma variação aleatória nesse tempo, evita que vários clientes tentem exatamente no mesmo instante. Na prática, em vez de esperar exatamente 4 segundos, você espera um valor entre 0 e 4 segundos. Isso espalha as requisições no tempo e reduz a chance de sobrecarregar o servidor. **Erro comum a evitar:** usar backoff sem jitter. Em um sistema com muitos clientes, todos seguindo a mesma progressão, o servidor recebe rajadas de requisições a cada intervalo. O jitter quebra esse padrão. **Dica:** implemente o jitter com uma função aleatória simples, como random.uniform(0, base), onde base é o valor do backoff atual. Bibliotecas como Resilience4j e Polly já incluem isso prontas para usar. ## Passo 5: Combine timeout e retry na mesma política Timeout e retry não são conceitos separados, eles trabalham juntos. O timeout define o limite de cada tentativa, e o retry define quantas vezes você tenta dentro de um limite global de tempo. Um padrão comum é: timeout de 3 segundos por tentativa, com até 3 tentativas e backoff de 1 a 4 segundos. O tempo total máximo, somando tentativas e esperas, fica em torno de 15 segundos. Se a operação precisa de uma resposta mais rápida, reduza o número de tentativas. **Erro comum a evitar:** definir timeout e retry separados, sem pensar no tempo total. Uma política com timeout de 30 segundos e 5 tentativas pode levar minutos para falhar, o que inviabiliza qualquer resposta em tempo real. **Dica:** defina um limite global de tempo para a operação completa. Se o retry estourar esse limite, cancele e retorne o erro ao chamador. ## Passo 6: Monitore e ajuste com base em dados reais Nenhuma política de timeout e retry sai perfeita de primeira. Você precisa observar como as chamadas se comportam em produção: quantas falhas ocorrem, quanto tempo cada tentativa leva, quantas respostas vêm atrasadas. Use métricas como taxa de erro, tempo médio de resposta e número de retries por chamada. Se a taxa de retries está alta, o servidor pode estar instável ou o timeout curto demais. Se o retry raramente resolve, talvez o erro não seja transitório. **Erro comum a evitar:** configurar uma vez e nunca mais revisar. O comportamento da rede e dos servidores muda com o tempo. O que funcionou no lançamento pode não funcionar depois de um aumento de tráfego. **Dica:** comece com valores conservadores e ajuste aos poucos. Altere uma variável por vez e observe o impacto antes de mudar a próxima. ## Checklist rápido Antes de colocar sua política em produção, confira: - Timeouts definidos por tipo de chamada, não global - Retry apenas para códigos de erro transitórios - Número máximo de tentativas limitado, entre 2 e 5 - Backoff exponencial com jitter implementado - Tempo total da operação dentro do limite aceitável - Métricas de monitoramento em lugar para avaliar o comportamento ## FAQ ### Devo usar timeout e retry em todas as chamadas HTTP? Sim, em praticamente todas as chamadas externas. Mas os valores variam. Chamadas internas entre serviços podem ter timeouts mais curtos, porque a latência é menor. Chamadas a APIs de terceiros, com SLA menos rígido, podem precisar de margens maiores. O importante é que exista um limite, para não travar sua aplicação. ### Qual é a diferença entre timeout e retry? Timeout define o tempo máximo que você espera por uma resposta. Se o tempo esgotar, a chamada é cancelada. Retry define quantas vezes você refaz a chamada depois de uma falha. Eles se complementam: o timeout controla cada tentativa, o retry controla o número de tentativas. ### O que é backoff exponencial? É uma estratégia de espera entre tentativas de retry. Em vez de tentar novamente no mesmo intervalo, você aumenta o tempo de espera a cada tentativa: 1 segundo, 2 segundos, 4 segundos. Isso dá tempo para o servidor se recuperar e evita sobrecarregá-lo com requisições repetidas. ### Posso aplicar retry em chamadas não idempotentes? Pode, mas com cautela. Operações como criação de recursos podem duplicar dados se a resposta se perder. Nesses casos, use um identificador de idempotência na requisição, para que o servidor reconheça a repetição e não crie um novo recurso. Ou limite o retry a falhas de conexão antes do envio. ### Qual é um bom valor de timeout para uma API pública? Depende da operação. Para leituras simples, 2 a 5 segundos é um ponto de partida comum. Para operações mais pesadas, como relatórios, 30 segundos pode ser aceitável. O importante é medir o tempo de resposta normal e definir o timeout acima do percentil 95, com margem para variações. ### Como evitar que o retry sobrecarregue o servidor? Use backoff exponencial com jitter e limite o número de tentativas. O jitter espalha as requisições no tempo, evitando picos sincronizados. Além disso, monitore a taxa de erros e ajuste a política se o servidor continuar recebendo muitas requisições repetidas. --- Fonte (canonical): https://posup.com.br/apps-e-software/timeout-e-retry-policies-em-http-guia-pratico/