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.
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 comnameigual 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.
// 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.
// 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.
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.
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:
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).
| Aspecto | Navegador | Node.js |
|---|---|---|
| Implementação | Especificação WHATWG do motor do browser | Implementação integrada ao runtime; para detalhes, consulte a documentação oficial do Node.js |
| CORS | Bloqueia resposta cross-origin sem headers corretos | Comportamento de CORS fora do escopo deste tutorial; consulte a documentação oficial do Node.js/undici |
Cookies (credentials) | Envia cookies same-origin por padrão | Tratamento de cookies fora do escopo deste tutorial; consulte a documentação oficial do Node.js/undici |
| Proxy | Segue a configuração do sistema/navegador | Configuração de proxy fora do escopo deste tutorial; consulte a documentação oficial do Node.js/undici |
AbortSignal.timeout() | Suportado em navegadores modernos | Suporte 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
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.
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.