Padronização de Erros no Fetch API: um avanço crucial para diagnóstico de redes

A forma como o Fetch API lida com erros de rede é uma fonte constante de frustração para desenvolvedores. Atualmente, qualquer falha de conexão, seja um problema de DNS, um erro de handshake TLS ou um reset de stream HTTP/2, resulta no mesmo e genérico TypeError. Essa falta de granularidade esconde informações cruciais para o diagnóstico e recuperação de falhas.

Protocolos modernos como HTTP/2 e HTTP/3 trazem códigos de erro detalhados que informam a causa exata de uma interrupção. Por exemplo, REFUSED_STREAM (HTTP/2) ou H3_REQUEST_REJECTED (HTTP/3) sinalizam que um pedido nunca foi processado e pode ser retentado com segurança, mesmo se não for idempotente. O Fetch API ignora esses sinais, tratando todos como um erro opaco e destruindo a capacidade de construir aplicações mais resilientes.

Uma proposta ao TC39 busca resolver isso ao padronizar uma propriedade .code em objetos Error. Isso permitiria que o Fetch API expusesse um código abstrato para o erro de rede, sem alterar sua superfície de API. Essa melhoria elevaria o patamar de depuração, otimização de requisições e, por consequência, a experiência do desenvolvedor (DX) no manejo de falhas de rede. A especificação seria cuidadosa em limitar a exposição de códigos de baixo nível em contextos cross-origin, preservando a segurança do navegador.

A ideia de adicionar uma propriedade .code a objetos Error não é nova no ecossistema JavaScript. Desde 2017, runtimes como Node.js já incorporam essa prática, e ferramentas como Deno e Bun (mencionada na nossa cobertura de 11 de julho de 2026 sobre a migração do Bun para Rust) seguiram o mesmo caminho. Muitos frameworks e bibliotecas também adotaram essa convenção.

O que muda agora é a busca por uma padronização oficial no nível da linguagem. A proposta atual no TC39, avançando para Stage 2.7, visa abençoar essa propriedade, dando-lhe semântica definida no construtor e garantindo que sobreviva a clonagem estruturada e transferências entre realms. Essa formalização do que já era um padrão de fato é um passo importante para a consistência e interoperabilidade no desenvolvimento web.

Para o desenvolvedor, a padronização dos códigos de erro no Fetch API significa um ganho significativo em capacidade de diagnóstico e tratamento de falhas. Em vez de um TypeError genérico, será possível identificar a causa exata de uma interrupção na rede. Isso permite implementar lógicas de re-tentativa inteligentes, distinguindo entre erros transitórios e falhas permanentes.

A clareza nos erros de rede leva a aplicações mais robustas e com melhor performance, minimizando o tempo de inatividade e otimizando o uso de recursos. Além disso, a melhoria na depuração e na compreensão das interações de rede impacta diretamente a produtividade, liberando tempo para focar em funcionalidades e na experiência do usuário, em vez de caçar bugs opacos.