--- title: "Corrija o erro Failed to fetch e distinga as 3 causas" description: "TypeError: Failed to fetch significa que a requisição não recebeu resposta HTTP. Um cabeçalho CORS ausente, um servidor fora do ar e um host que não existe dão a mesma mensagem." canonical: "https://logbrew.co/pt-BR/errors/failed-to-fetch" last_updated: "2026-11-10" --- # Corrija o erro Failed to fetch e distinga as 3 causas `TypeError: Failed to fetch` significa que a requisição não recebeu resposta HTTP. Um cabeçalho CORS ausente, um servidor fora do ar e um host que não existe dão a mesma mensagem. Testado em 10 de novembro de 2026 com Chromium 152, @logbrew/browser 0.1.21 e @logbrew/sdk 0.1.44 Por [Furkan Erday](https://github.com/furkanerday). Furkan Erday é o fundador do LogBrew. Ele desenvolve o LogBrew com Claude Code e Codex todos os dias. Canonical: https://logbrew.co/pt-BR/errors/failed-to-fetch ## O que indica a causa de um `fetch()` que falhou | O que deu errado | `error.message` | Console | | --- | --- | --- | | Sem o cabeçalho `Access-Control-Allow-Origin` | `Failed to fetch` | Política CORS | | Nada escuta na porta | `Failed to fetch` | `ERR_CONNECTION_REFUSED` | | O host não tem registro DNS | `Failed to fetch` | `ERR_NAME_NOT_RESOLVED` | | O servidor respondeu 500 | Não rejeitou | `500` | 4 requisições para uma API em outra origem. Uma caneca cheia significa que o texto indica a causa. ## Descubra qual causa você tem ### Abra o console do navegador `fetch()` rejeita com o mesmo `TypeError: Failed to fetch` para toda falha de rede. A linha do console ao lado indica a causa real. ### A API respondeu sem cabeçalho CORS O console diz `blocked by CORS policy`. O servidor respondeu, mas a origem da página não tem permissão para ler a resposta, então o navegador descarta a resposta. Saída ```text Access to fetch at 'http://127.0.0.1:4874/api/closed' from origin 'http://127.0.0.1:4873' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. ``` ### Nada escuta nesse host e porta O console diz `net::ERR_CONNECTION_REFUSED`. A API não está rodando, ou a porta na URL está errada. Inicie a API, depois confira a porta. Saída ```text Failed to load resource: net::ERR_CONNECTION_REFUSED ``` ### O nome do host não resolve O console diz `net::ERR_NAME_NOT_RESOLVED`. O DNS não tem registro para o host. Confira se o hostname tem erro de digitação, e a variável de ambiente que guarda a URL da API nesta implantação. Saída ```text Failed to load resource: net::ERR_NAME_NOT_RESOLVED ``` ## Corrija no seu código ### Envie o cabeçalho CORS da API Responda com `Access-Control-Allow-Origin` definido como a origem da sua página, ou `*` para uma API pública. No nosso teste, o mesmo endpoint passou de `Failed to fetch` para `HTTP 200` só com esse cabeçalho adicionado. ```bash Access-Control-Allow-Origin: https://app.example.com ``` ### Confira o status, porque um 500 não rejeita `fetch()` resolve em qualquer resposta HTTP, inclusive 404 e 500. No nosso teste, um 500 com o corpo `{"error":"tap jammed"}` chegou ao `then`, não ao `catch`. Teste `response.ok` antes de ler o corpo. ```bash const response = await fetch(url); if (!response.ok) throw new Error(`HTTP ${response.status} for ${url}`); ``` ### Registre a URL junto com o erro Um `fetch()` rejeitado não tem resposta, e o stack trace dele aponta para o seu próprio código, não para a causa. Capture o erro onde você chama `fetch()` e guarde o método e a URL junto com ele, para o seu rastreamento de erros mostrar qual requisição falhou. ```bash try { return await fetch(url); } catch (error) { console.error("fetch failed", url, error); throw error; } ``` ## O que vimos no teste A página rodou em `http://127.0.0.1:4873` no Chromium 152 com o `@logbrew/browser` 0.1.21 e a instrumentação de fetch instalada. Uma API em `http://127.0.0.1:4874` respondia a 3 caminhos, e enviamos 5 requisições sem `catch`, então cada rejeição chegou ao SDK como rejeição não tratada. `/api/closed` respondeu 200 sem cabeçalho CORS, e a requisição rejeitou com `TypeError: Failed to fetch`. Uma requisição para a porta 4875, onde nada escutava, e uma para `http://keg.invalid/api` rejeitaram com o mesmo erro. Nos 3 casos, `error.message` era `Failed to fetch`, `error.name` era `TypeError`, e o stack trace apontava para a nossa própria chamada de `fetch()`. O console diferenciou os casos. O primeiro dizia `blocked by CORS policy`, o segundo `net::ERR_CONNECTION_REFUSED`, o terceiro `net::ERR_NAME_NOT_RESOLVED`. `/api/broken`, que respondeu 500 com o cabeçalho, não rejeitou, e `/api/open`, que respondeu 200 com o cabeçalho, deu `HTTP 200 {"ok":true}`. ## Por que toda causa tem a mesma mensagem O Fetch Standard transforma toda falha antes de uma resposta em 1 coisa, um erro de rede, que é uma resposta com tipo `error` e status 0. Uma falha de CORS também é um erro de rede. No modo `cors`, um recurso que não entende o protocolo CORS dá um erro de rede. O método `fetch()` rejeita a promise com um `TypeError` para um erro de rede, e para nada mais. O MDN diz o mesmo. A promise só rejeita quando a requisição falha, por exemplo com uma URL malformada ou um erro de rede, e não com um status HTTP como 404 ou 504. A página do MDN sobre erros de CORS diz que os detalhes de uma requisição CORS que falhou não ficam disponíveis para o JavaScript por motivos de segurança, e que o console é o único lugar para encontrá-los. A whatwg/fetch#526 pede tipos de erro mais informativos desde 2017 e continua aberta. ## O que o LogBrew registra Cada rejeição chegou como 1 problema chamado `Unhandled promise rejection: TypeError`, com frames de stack no nosso bundle e a chave de agrupamento `browser.unhandledrejection:TypeError:/app.js`. Isso diz onde você chamou `fetch()`, não o que falhou. A instrumentação de fetch adicionou um span no mesmo trace, `browser.fetch GET /api/closed`, com status `error`, o método, o caminho da requisição e `errorType` `TypeError`. O span nomeia a requisição que falhou, mesmo que o erro não nomeie. A resposta 500 não gerou problema, só um span com status `error` e `statusCode` 500. A resposta 200 gerou um span com status `ok`. Então, no LogBrew, um 500 e uma falha de rede são 2 spans diferentes, enquanto no seu código só a segunda chega ao `catch`. ## Perguntas frequentes ### O que significa TypeError Failed to fetch? O navegador não conseguiu obter uma resposta HTTP para uma chamada de `fetch()`. O servidor estava inacessível, o host não resolveu ou o CORS bloqueou a resposta. A mensagem é a mesma nos 3 casos. ### Failed to fetch é sempre um erro de CORS? Não. No nosso teste, um cabeçalho CORS ausente, uma porta sem servidor e um host sem registro DNS deram essa mensagem. Só a linha do console ao lado indica a causa. ### Por que o fetch não rejeita em um 404 ou 500? O Fetch Standard só rejeita em um erro de rede. Uma resposta HTTP com qualquer status é uma resposta, então `fetch()` resolve e você mesmo testa `response.ok`. ### Como capturo Failed to fetch em JavaScript? Envolva a chamada em `try` e `catch`, ou adicione `.catch()` à promise. O erro é um `TypeError` sem resposta, então registre a URL e o método você mesmo. ### Failed to fetch significa que o servidor caiu? Às vezes. Um servidor fora do ar dá `net::ERR_CONNECTION_REFUSED` no console. O mesmo `Failed to fetch` também vem de um cabeçalho CORS ausente ou de um host sem registro DNS. ## Veja qual requisição falhou, e por quê O SDK de navegador do LogBrew registra cada `fetch()` como um span com método, caminho e status, no mesmo trace do erro que ele gerou. Comece no plano gratuito generoso, sem cartão. [Comece grátis](https://logbrew.co/pt-BR) ## Fontes - [MDN, Window: fetch() method](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) - [MDN, CORS errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS/Errors) - [Fetch Standard, The fetch() method](https://fetch.spec.whatwg.org/#fetch-method) - [whatwg/fetch#526](https://github.com/whatwg/fetch/issues/526) ## Mais correções de erros de JavaScript - [Corrija o erro de script que esconde a mensagem, o arquivo e a linha](https://logbrew.co/pt-BR/errors/script-error) - [Erros de JavaScript que reproduzimos, e como corrigir cada um](https://logbrew.co/pt-BR/errors)