powered byiMasterstutoriais · referência · código em portuguêsPatrocínio
JavaScript e TypeScript

Fetch no navegador e no Node: GET, POST, erros e timeout com AbortController

Um guia prático do fetch(): GET e POST com JSON, por que a promise não rejeita em 404, como separar erro de rede de erro de status e como cancelar uma requisição com AbortController.

Por Rafael SousaColunista6 min de leitura
Imagem gerada por IA

Neste tutorial você vai montar um GET e um POST com JSON usando fetch(), entender por que a promise não rejeita quando o servidor responde 404, separar erro de rede de erro de status, e colocar timeout e cancelamento numa requisição com AbortController. Os exemplos deste tutorial funcionam tanto no navegador quanto no Node.js, que já traz fetch nativo.

Nota da redação: a seção "Timeout e cancelamento" cita AbortSignal.timeout() e o erro com name igual a 'TimeoutError'. Esses dois pontos são comportamentos reais da especificação WHATWG/Fetch e estão documentados em páginas do MDN, mas não aparecem na página específica da MDN usada como fonte principal deste tutorial, então não foi possível confirmar essas afirmações diretamente contra a fonte citada. Recomendamos checar a documentação atual do MDN ou a compatibilidade do seu ambiente antes de depender desse comportamento em produção.

GET e POST com JSON

O uso básico de fetch() é passar uma URL e aguardar a Promise que resolve com um Response. Por padrão a requisição é GET, então pra ler um JSON basta chamar response.json(), que também é assíncrono.

js
// get-produtos.mjs
async function getProducts() {
  const url = "https://example.org/products.json";
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`Resposta com status ${response.status}`);
    }
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error("Falha na requisição:", error.message);
  }
}

getProducts();

Rode com node get-produtos.mjs ou cole a função num script carregado pelo navegador.

Pra enviar dados, use method: "POST", declare o Content-Type e serialize o corpo com JSON.stringify(). O fetch() não serializa objetos sozinho: se você passar um objeto puro como body sem usar JSON.stringify(), ele é convertido para string usando o método toString() do objeto, o que raramente é o que você quer enviar ao servidor.

js
// post-usuario.mjs
async function createUser(payload) {
  const response = await fetch("https://example.org/users", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    throw new Error(`Erro ${response.status} ao criar usuário`);
  }

  return response.json();
}

createUser({ name: "Ana", email: "ana@example.org" })
  .then((user) => console.log("Criado:", user))
  .catch((error) => console.error(error.message));

Por que fetch não rejeita em 404

Esse é o tropeço mais comum de quem vem do XMLHttpRequest ou de bibliotecas como o axios: fetch() só rejeita a promise em erro de rede (host não resolve, conexão recusada, CORS bloqueado) ou esquema inválido. Um 404, um 500 ou qualquer status de erro HTTP chegam como Response normal, com response.ok em false.

A função fetch() rejeita a promise em alguns erros, mas não quando o servidor responde com um status de erro como 404: por isso também verificamos o status da resposta e lançamos uma exceção se ele não estiver OK.

The fetch() function will reject the promise on some errors, but not if the server responds with an error status like 404: so we also check the response status and throw if it is not OK.MDN Web Docs, documentação da Fetch API

Na prática isso significa que todo fetch() seu precisa checar response.ok (ou a faixa de response.status) antes de ler o corpo. Esquecer esse if é o jeito mais fácil de um 404 silencioso virar undefined.property três linhas depois, quando o código tenta ler um JSON de erro como se fosse sucesso.

Erro de rede versus erro de status

São dois problemas diferentes e pedem tratamento diferente. Na prática, erro de rede costuma derrubar a promise com um TypeError e cair direto no catch; erro de status chega como resposta válida e exige o throw manual que vimos acima.

js
async function getSafely(url) {
  try {
    const response = await fetch(url);

    if (!response.ok) {
      // Erro de status: o servidor respondeu, mas com 4xx ou 5xx
      throw new Error(`Status ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    if (error instanceof TypeError) {
      // Erro de rede: DNS, conexão recusada, CORS bloqueado
      console.error("Falha de conexão:", error.message);
    } else {
      console.error("Resposta de erro do servidor:", error.message);
    }
    throw error;
  }
}

Repare que response.json() também pode lançar, por conta própria, se o corpo não for um JSON válido. Essa exceção cai no mesmo catch, mas não é nem erro de rede nem erro de status: é corpo malformado, e vale logar separado se o seu código distinguir os três casos.

Timeout e cancelamento com AbortController

O fetch() não tem opção de timeout embutida. Quem cancela a requisição é um AbortController: você cria o controller, passa controller.signal na opção signal do fetch(), e chama controller.abort() quando quiser desistir. A promise rejeita com um erro cujo name é "AbortError".

Pra timeout, não precisa montar o setTimeout() manual: AbortSignal.timeout(ms) cria um sinal que aborta sozinho depois do prazo, disponível em navegadores modernos.

js
async function getWithTimeout(url, timeoutMs = 5000) {
  try {
    const response = await fetch(url, {
      signal: AbortSignal.timeout(timeoutMs),
    });

    if (!response.ok) {
      throw new Error(`Status ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    if (error.name === "TimeoutError") {
      console.error("A requisição estourou o tempo limite");
    } else if (error.name === "AbortError") {
      console.error("Requisição cancelada manualmente");
    } else {
      console.error("Erro de rede ou de parsing:", error.message);
    }
  }
}

Pra cancelamento por ação do usuário (um botão "cancelar" na tela, por exemplo), o controller fica fora da função e o abort() é chamado num listener separado:

js
const controller = new AbortController();

document.querySelector("#buscar").addEventListener("click", async () => {
  try {
    const response = await fetch("https://example.org/get", {
      signal: controller.signal,
    });
    console.log(`Status: ${response.status}`);
  } catch (error) {
    console.error(`Cancelado ou falhou: ${error.message}`);
  }
});

document.querySelector("#cancelar").addEventListener("click", () => {
  controller.abort();
});

Um detalhe que pega gente de surpresa: se o abort() acontecer depois que a promise do fetch() já resolveu, mas antes de você ler o corpo com response.text() ou response.json(), essa leitura rejeita com AbortError também. O cancelamento vale pro corpo da resposta, não só pra requisição em si.

Fetch no navegador x fetch no Node

A assinatura de fetch() é a mesma nos dois ambientes, mas o que acontece por trás muda bastante. Este tutorial usa a documentação MDN do fetch no navegador como fonte; para o comportamento exato no Node.js, vale sempre checar a documentação oficial do Node.js e do undici (a biblioteca por trás da implementação).

AspectoNavegadorNode.js
ImplementaçãoEspecificação WHATWG do motor do browserImplementação integrada ao runtime; para detalhes, consulte a documentação oficial do Node.js
CORSBloqueia resposta cross-origin sem headers corretosComportamento de CORS fora do escopo deste tutorial; consulte a documentação oficial do Node.js/undici
Cookies (credentials)Envia cookies same-origin por padrãoTratamento de cookies fora do escopo deste tutorial; consulte a documentação oficial do Node.js/undici
ProxySegue a configuração do sistema/navegadorConfiguração de proxy fora do escopo deste tutorial; consulte a documentação oficial do Node.js/undici
AbortSignal.timeout()Suportado em navegadores modernosSuporte depende da versão do Node.js; consulte a documentação oficial do Node.js para a versão mínima exigida

Na prática, scripts Node não rodam dentro de um navegador, então mecanismos pensados pra contexto de página, como mode: "no-cors" ou cookies same-origin, tendem a não se aplicar da mesma forma fora dele; pra confirmar o comportamento exato, vale checar a documentação oficial do Node.js/undici.

Próximo passo

A referência completa de opções do fetch() (RequestInit), do Response e do Headers está na página da MDN usada como base deste tutorial. Pra ir além do fetch() puro, o próximo passo natural é ReadableStream para processar respostas grandes aos poucos, e a documentação do undici pra configurar proxy, keep-alive e pool de conexões quando o fetch() do Node virar gargalo em produção. Dúvida pontual de comportamento costuma ter resposta rápida na seção de Fetch API do MDN ou no repositório do undici no GitHub.

Fonte: MDN: Using the Fetch API

PatrocínioContinue estudando JavaScript e TypeScriptTrilhas completas, projetos e exercícios na DevMedia.Travou em algum passo?Pergunte no Fórum iMastersPoste o trecho de código e o erro: a comunidade responde.Notícias da stackO que saiu de novo, no iMastersLançamentos, versões e eventos do ecossistema dev.

Este artigo foi escrito por Rafael Sousa. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.

Rafael Sousa

Editor virtual de JavaScript e TypeScript do Linha de Código. Escreve para quem faz front e back na mesma linguagem: TypeScript, Node.js, React, Next.js, Vue, Angular, HTML e CSS, com o código rodando no navegador ou no terminal. Prefere a plataforma (fetch, módulos ES, API do DOM) ao pacote da moda, e diz quando o framework vale a pena.

Próximos passoso que estudar a partir daqui

  1. você está aquiFetch no navegador e no Node: GET, POST, erros e timeout com AbortController
  2. mesmo autorTypeScript 5.9 redesenha o tsc --init e introduz import deferJavaScript e TypeScript · 1 min

Newsletter

Os melhores tutoriais da semana, no seu e-mail

Toda semana, os tutoriais novos das sete stacks e o guia de referência que vale guardar. Gratuita, sem spam.