Timeout em requisições HTTP é aquele limite de tempo que impede seu aplicativo de ficar esperando para sempre por uma resposta. Sem ele, um servidor lento ou fora do ar pode travar a interface do usuário, gerar filas de requisições e derrubar o serviço inteiro. Neste guia, você vai aprender a implementar timeout corretamente, tanto no cliente quanto no servidor, com exemplos práticos e erros comuns a evitar.
Passo 1: Defina o timeout no cliente com Axios ou Fetch
No lado do cliente, a forma mais simples é usar o Axios, que aceita um parâmetro timeout em milissegundos. Por exemplo, axios.get('/api/dados', { timeout: 5000 }) define 5 segundos de espera. Se a resposta não chegar, a requisição é cancelada e um erro é lançado.
Com o Fetch API nativo, o processo é um pouco mais manual: você precisa usar o AbortController. Crie um controller, passe o sinal para o fetch e use setTimeout para abortar após o tempo desejado. Veja um exemplo:
const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 5000);
try { const response = await fetch('/api/dados', { signal: controller.signal }); clearTimeout(timeoutId); } catch (error) { if (error.name === 'AbortError') { console.log('Requisição cancelada por timeout'); } }
Erro comum: esquecer de limpar o setTimeout após a resposta. Isso pode causar memory leaks e aborts indesejados em requisições seguintes.
Passo 2: Configure o timeout no servidor
No servidor, o timeout protege seus recursos de requisições que demoram demais. Em Node.js com Express, você pode usar o middleware timeout ou definir um limite no próprio http.createServer. Por exemplo, server.timeout = 10000 define 10 segundos para toda requisição.
Em outros servidores, como nginx, a diretiva proxy_read_timeout define quanto tempo esperar pela resposta do backend. O valor padrão é 60 segundos, mas para APIs, 10 a 30 segundos costuma ser suficiente. Se o backend não responder nesse período, o nginx retorna erro 504.
Erro comum: definir timeout apenas no servidor e esquecer do cliente. Quando o servidor derruba a conexão, o cliente pode ficar esperando até o próprio timeout, o que dobra o tempo de espera.
Passo 3: Escolha valores adequados e trate erros
Não existe um valor mágico de timeout. Ele depende do que sua aplicação faz. Uma API de consulta a CEP, por exemplo, pode responder em menos de 1 segundo, então 5 segundos é generoso. Já um endpoint que processa relatórios pesados pode precisar de 30 segundos ou mais. O importante é medir o tempo real de resposta em produção e ajustar.
Ao tratar o erro de timeout, retorne uma mensagem clara ao usuário, como "Serviço indisponível, tente novamente". Não é só logar o erro no console. Em APIs, use o código HTTP 504 (Gateway Timeout) ou 408 (Request Timeout), dependendo de quem detectou o problema.
Erro comum: usar o mesmo timeout para todas as requisições. Uma operação de upload de arquivo grande não pode ter o mesmo limite de uma consulta simples. Separe os endpoints por criticidade.
Checklist final
- Cliente define timeout com Axios ou AbortController no Fetch
- Servidor define timeout no Express, nginx ou equivalente
- Valores de timeout baseados em medição real, não chute
- Erros de timeout tratados com mensagem amigável ao usuário
- Timeouts diferentes para operações diferentes
FAQ
O que é timeout em requisições HTTP?
É o tempo máximo que o cliente ou servidor espera por uma resposta antes de cancelar a operação. Sem ele, uma requisição pode ficar pendente indefinidamente, consumindo recursos e travando a aplicação.
Qual a diferença entre timeout no cliente e no servidor?
No cliente, o timeout evita que o usuário fique esperando. No servidor, protege os recursos do servidor de requisições lentas. Ambos são importantes e devem ser configurados em conjunto, com valores compatíveis.
O que acontece quando o timeout é atingido?
A requisição é cancelada e um erro é lançado. No cliente, você pode capturar esse erro e exibir uma mensagem. No servidor, a conexão é encerrada e um status HTTP como 408 ou 504 é retornado.
Como escolher o valor ideal de timeout?
Meça o tempo de resposta da sua API em condições normais e sob carga. Defina um timeout que seja pelo menos o dobro do tempo médio, mas não tão alto que esconda problemas reais. Para APIs públicas, 5 a 10 segundos é um bom ponto de partida.
Timeout é a mesma coisa que retry?
Não. Timeout é o limite de espera. Retry é tentar novamente após uma falha. Eles podem ser usados juntos, mas retry sem timeout pode causar loops infinitos. Sempre combine os dois com cautela.
Fetch API tem timeout nativo?
Não. O Fetch não tem um parâmetro de timeout como o Axios. Você precisa usar o AbortController e um setTimeout manual, como mostrado no Passo 1. Isso adiciona um pouco de complexidade, mas é simples de implementar.