Como Depurar Erros de CORS no Navegador

Apr 21, 2026 · 4 min read

Você dispara uma requisição fetch, abre o console e vê algo como:

Access to fetch at ‘https://api.example.com’ from origin ‘http://localhost:3000’ has been blocked by CORS policy.

Antes de começar a alterar cabeçalhos do servidor aleatoriamente, pare. A maioria da depuração de CORS no navegador se resume a ler o que o navegador já está te dizendo — se você souber onde procurar.

Pontos-Chave

Erros de CORS são aplicados pelo navegador, não pelo servidor. A requisição frequentemente chega ao servidor; o bloqueio acontece na resposta.
A mensagem do console do navegador é sua principal ferramenta de diagnóstico — ela geralmente aponta para a regra ou cabeçalho com falha, mas também pode refletir problemas subjacentes de rede, TLS ou política.
Requisições preflight OPTIONS falham silenciosamente se você não estiver procurando por elas. Sempre verifique a aba Network filtrada por “All” para identificá-las.
Nem todo erro que parece ser CORS é realmente um problema de CORS. Conteúdo misto, falhas de TLS, redirecionamentos e extensões do navegador podem se disfarçar como problemas de CORS.

O Que os Erros de CORS Realmente Significam

Erros de CORS (Cross-Origin Resource Sharing) ocorrem quando seu navegador bloqueia uma requisição cross-origin porque a resposta do servidor não incluiu as permissões corretas. A palavra-chave é navegador — a requisição frequentemente chega ao servidor. O bloqueio acontece no caminho de volta.

Uma origem é definida pela combinação de protocolo, domínio e porta. Então http://localhost:3000 e http://localhost:4000 são origens diferentes, mesmo na mesma máquina.

Como Depurar Erros de CORS Usando DevTools

Abra DevTools → aba Network (F12 ou Cmd+Option+I). Reproduza a requisição com falha. Então:

Encontre a requisição com falha — procure por uma entrada vermelha ou filtre por “Fetch/XHR.”
Verifique a aba Console — a mensagem de erro ali é específica. Ela te diz qual cabeçalho está faltando ou incompatível.
Clique na requisição → aba Headers — inspecione tanto os cabeçalhos da requisição (especialmente Origin) quanto os cabeçalhos da resposta (especialmente Access-Control-Allow-Origin).

O erro do console é sua principal ferramenta de diagnóstico. Chrome e Firefox modernos fornecem mensagens precisas como:

“No ‘Access-Control-Allow-Origin’ header is present” → o servidor não enviou nenhum cabeçalho CORS.
“The value of ‘Access-Control-Allow-Origin’ must not be the wildcard ’*’ when credentials mode is ‘include’” → você está usando credentials: 'include' mas o servidor respondeu com *.
“Method PUT is not allowed by Access-Control-Allow-Methods” → o preflight rejeitou seu método HTTP.

Depurando Requisições Preflight (OPTIONS)

Quando sua requisição usa um método não-simples (PUT, DELETE, PATCH), cabeçalhos customizados, ou um content type diferente dos poucos permitidos pela especificação, o navegador envia uma requisição preflight OPTIONS primeiro. Se isso falhar, sua requisição real nunca é enviada.

Na aba Network, filtre por “All” e procure por uma requisição OPTIONS para a mesma URL, aparecendo logo antes da sua requisição principal. Clique nela e verifique:

Cabeçalhos da requisição: Access-Control-Request-Method e Access-Control-Request-Headers — estes informam ao servidor o que a requisição real precisa.
Cabeçalhos da resposta: Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Origin — o servidor deve permitir explicitamente cada um.

Se a requisição OPTIONS retornar um código de status 4xx ou 5xx, isso provavelmente é um erro de roteamento ou configuração do lado do servidor, não uma configuração incorreta de cabeçalho CORS. Corrija o erro subjacente primeiro.

É Realmente um Erro de CORS?

Nem todo erro que aparece como CORS é causado por CORS. Falsos positivos comuns incluem:

Conteúdo misto — buscar http:// de uma página https:// é bloqueado pela política de conteúdo misto do navegador, independentemente dos cabeçalhos CORS.
Erros de TLS/certificado — uma falha no handshake TLS pode parecer uma falha de CORS no console.
Redirecionamentos para uma origem diferente — se o servidor redirecionar sua requisição para uma nova origem, o navegador bloqueia a requisição. Redirecionamentos cross-origin não são permitidos para requisições CORS.
Extensões do navegador — extensões de privacidade ou bloqueio de anúncios podem cancelar requisições antes mesmo do CORS ser avaliado.
Restrições de cookies de terceiros — se você está usando credentials: 'include', navegadores modernos podem bloquear cookies de origens de terceiros mesmo quando seus cabeçalhos CORS estão perfeitamente corretos.

Para isolar a causa real, tente a requisição em uma janela privada/anônima com extensões desabilitadas.

Requisições com Credenciais: Uma Armadilha Comum

Se você usar fetch(url, { credentials: 'include' }), o servidor não pode responder com Access-Control-Allow-Origin: *. Ele deve retornar exatamente a origem solicitante. O servidor também precisa incluir Access-Control-Allow-Credentials: true em sua resposta. Perca qualquer um deles e o navegador bloqueia a resposta.

Checklist Rápido de Depuração de CORS

Verificação	O Que Procurar
Mensagem de erro do console	Cabeçalho ou regra exata que falhou
Requisição OPTIONS presente?	Preflight disparado — verifique sua resposta
Resposta tem `Access-Control-Allow-Origin`?	Deve corresponder à sua origem ou ser `*`
Usando credenciais?	`*` não é permitido; origem exata necessária
4xx/5xx na requisição?	Erro do servidor — não é um problema de CORS
Conteúdo misto?	HTTP de página HTTPS — sempre bloqueado

Conclusão

A mensagem de erro do navegador, a aba Network e o painel Headers fornecem tudo que você precisa para diagnosticar a maioria dos problemas de CORS em menos de cinco minutos. Leia o erro exato, encontre a requisição OPTIONS se existir uma, compare o que foi enviado com o que era esperado, e trabalhe a partir daí. Resista ao impulso de adicionar cegamente Access-Control-Allow-Origin: * ao seu servidor — entenda primeiro o que o navegador está pedindo e responda com precisão.

Perguntas Frequentes

Não. CORS é aplicado pelo navegador com base nos cabeçalhos que o servidor envia. O frontend não pode sobrescrever isso. Se você não controla o servidor, pode rotear requisições através de um proxy backend que adiciona os cabeçalhos corretos, mas o código do lado do navegador sozinho não pode contornar a restrição.

O Postman não é um navegador e não aplica a política de mesma origem. Ele envia requisições diretamente sem verificar cabeçalhos CORS na resposta. Navegadores aplicam CORS para proteger usuários, então uma requisição que tem sucesso no Postman ainda pode ser bloqueada pelo navegador se o servidor omitir os cabeçalhos de resposta necessários.

Um preflight é disparado quando a requisição usa um método diferente de GET, HEAD ou POST, inclui cabeçalhos customizados, ou define um Content-Type diferente de application/x-www-form-urlencoded, multipart/form-data ou text/plain. O navegador envia uma requisição OPTIONS primeiro para confirmar que o servidor permite a requisição real.

Se sua requisição inclui credenciais como cookies ou cabeçalhos de autorização, o servidor não pode usar o valor wildcard. Ele deve responder com a origem exata que fez a requisição e também incluir o cabeçalho Access-Control-Allow-Credentials definido como true. O wildcard só é válido para requisições sem credenciais.

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.