O problema que ninguém quer enfrentar
A melhor forma de entender um network error é parar de tratá-lo como uma mensagem de erro genérica e começar a pensar nele como um sintoma. Quando você vê isso na tela, na prática significa que a camada de rede entre dois pontos falhou em estabelecer, manter ou completar uma transmissão de dados. Ponto. O resto é investigar qual camadinha do protocolo que quebrou. No meu caso, trabalhando com integração de APIs há anos, já vi isso acontecer por causas tão diferentes que parecem impossíveis numa primeira olhada. Uma vez, um cliente nosso começou a receber network error intermitente em horários específicos do dia. Levou três semanas de investigação até descobrir que era o MTU do link do datacenter deles travando com pacotes IPv6 em rotas intermediárias. Workaround foi simples: ajustar o MSS clamping no firewall para 1440 bytes e o problema desapareceu. Não era um "erro de rede" qualquer, era uma configuração específica de fragmentation que ninguém tinha pensado em verificar.
O que significa network error na prática
Quando o sistema te mostra network error, ele está basicamente dizendo que tentou fazer algo na rede e não recebeu resposta dentro do prazo ou com os dados esperados. Isso pode abranger desde uma falha no DNS resolver até um timeout de TCP, um reset de conexão, ou até mesmo um drop silencioso de pacotes em algum hop intermediário. Aqui vai algo que poucas pessoas percebem: network error nem sempre significa que a rede está "caiada". Já depurei casos onde tudo estava fisicamente ok, mas o error vinha de um SSL renegotiation falho no meio do caminho, ou de um load balancer cortando conexões keep-alive de forma agressiva. O erro aparecia idêntico, mas a raiz era completamente diferente.
Como diagnosticar de verdade
O primeiro passo é parar de olhar para a mensagem de erro em si e começar a coletar dados. O que importa não é o que a API ou o navegador fala, é o que a rede fez antes daquela mensagem chegar até você. Aqui vai o método que eu uso: Comece com ping e traceroute básicos para mapear se há perda de pacotes ou latência anormal nos hops. Depois, se for HTTPS, rode wget --server-response ou curl -v para ver exatamente onde a conexão falha. Se o erro vier de um aplicativo específico, use tcpdump ou wireshark no host de origem para capturar o handshake completo. Anote o código de estado HTTP se houver, e o código de erro da lib de rede (errno) se estiver programando.
O detalhe que os débutants perdem: o network error pode vir de qualquer lugar entre seu client e o server final. Um CDN, um reverse proxy, um WAF, um ISP ruim. Eu já perdi horas caçando o que eu achava que era um bug no código, quando na verdade era um provider de DNS resolviendo IPs velhos porque o TTL estava configurado em 86400 segundos e o domínio tinha sido migrado duas semanas antes.
Códigos que você precisa conhecer
Redes usam padrões, e saber o que cada um significa economiza tempo que de outra forma você perderia tentando adivinhar. Os mais comuns que você vai encontrar: ECONNREFUSED — a máquina responde, mas não tem nada rodando na porta que você tentou conectar. É diferente de "rede indisponível", é "rede disponível mas serviço não existe".
ETIMEDOUT — nenhuma resposta veio dentro do window que o cliente espera. Pode ser firewall dropando pacotes, rota quebrada, ou o servidor simplesmente sobrecarregado. ENOTFOUND — o DNS não resolveu o nome. Mas cuidado: isso também pode acontecer quando o resolver do sistema tá pointing pra um DNS interno que não conhece o domínio, não necessariamente porque o domínio não existe.
👉 Clique no botão abaixo para saber mais sobre o assunto!
ERR_SSL_PROTOCOL_ERROR — handshake TLS falhou. Pode ser incompatibilidade de versões (client pede TLS 1.3, server só aceita 1.2), cert inválido, ou SNI não enviado corretamente. 502 Bad Gateway / 504 Gateway Timeout — isso é erro de proxy, não do client. O servidor de origem não respondeu ou respondeu errado para o intermediário.
Workarounds que funcionam no mundo real
Depois de isolar o problema, aqui vão soluções práticas baseadas no que eu vi funcionar: Se for problema de DNS, mude o resolver para 1.1.1.1 ou 8.8.8.8 temporariamente e teste. Se funcionar, o problema é no seu DNS padrão. Configure TTLs menores (300 segundos) em Produção para evitar cache stale.
Se for timeout, aumente o timeout do client em pelo menos 2x o que você acha necessário, mas antes verifique se não é o servidor que está lento. Use curl --max-time 30 para testar de forma controlada. Se for problema de MTU, como no caso que citei acima, faça um ping com o flag don't fragment (ping -M do -s 1472) e vá reduzindo o tamanho até encontrar o valor que passa sem fragmentação. Ajuste o MSS accordingly.
Se for conexão TLS, verifique a data/hora do sistema (certificação validity depende disso), atualize o CA bundle, e test com openssl s_client -connect host:port -tls1_2 para ver o handshake em detalhe.
O que network error NÃO é
É importante deixar claro: network error não é um diagnóstico. É um síntoma. Tratar o error como se fosse a causa raiz é o erro mais comum. Você pode corrigir o que aparece na tela e o problema continuar vindo porque a verdadeira causa está em outro lugar. Outro equívoco frequente é assumir que retry automático resolve tudo. Se você tem um network error causado por rate limiting ou sobrecarga do servidor, apenas retry sem backoff exponencial só piora a situação. Use jitter e backoff progressivo, e sempre limite o número máximo de tentativas.
Por fim, network error em produção raramente tem uma causa única. Em experiências minhas, os problemas mais persistentes foram aqueles onde dois fatores se combinavam: uma rota subótima somada a um timeout configurado muito apertado. Isolando um ou outro, o sistema parecia funcionar. Com os dois presentes, falhava de forma intermitente e inexplicável só de olhar os logs. Se você está encarando um network error agora, o caminho mais rápido não é googlar a mensagem de erro e aplicar a primeira solução que aparecer. É colecionar dados de rede, isolar a camada problemática, e tratar o error como um ponto de partida para investigação, não como o problema em si.
