CORS erro: o que é e como resolver os principais

O erro CORS (Cross-Origin Resource Sharing) é um bloqueio feito pelo navegador quando uma requisição HTTP parte de uma origem diferente daquela do servidor. Na prática, ele impede que um site acesse recursos de outro domínio sem permissão explícita. A correção exige ajustes no servidor, que deve responder com cabeçalhos específicos autorizando o acesso.

O que causa o erro CORS?

O navegador aplica a política de mesma origem por segurança. Se o seu front-end roda em http://localhost:3000 e a API em http://api.exemplo.com, a origem é diferente. O navegador então envia a requisição, mas bloqueia a resposta se o servidor não declarar que aceita aquela origem. O erro aparece no console, geralmente com a mensagem "Cross-Origin Request Blocked".

Como identificar o erro no console do navegador

Abra as ferramentas do desenvolvedor (F12) e vá até a aba Console. A mensagem de erro aponta a requisição exata que falhou, incluindo a URL e o método HTTP. No Mozilla Firefox, o texto costuma ser "Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource". Esse detalhe ajuda a saber se o problema está na configuração do servidor ou na ausência de um cabeçalho específico.

Como resolver no servidor (a solução principal)

A resposta definitiva vem do servidor. Ele precisa incluir o cabeçalho Access-Control-Allow-Origin na resposta HTTP. Se a API for pública, use *. Se houver autenticação, defina a origem exata, como https://meusite.com.br. Em Node.js com Express, um middleware simples resolve:

app.use((req, res, next) => { res.setHeader('Access-Control-Allow-Origin', '*'); res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE'); res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization'); next(); });

Em servidores Apache, adicione no .htaccess:

Header set Access-Control-Allow-Origin "*"

E se o problema for no front-end?

Atenção: o front-end não "resolve" CORS sozinho. Algumas bibliotecas prometem contornar, mas isso mascara o erro. Em ambiente de desenvolvimento, você pode usar um proxy, como o do Vite (server.proxy) ou o http-proxy-middleware do webpack. Em produção, a única via correta é ajustar o servidor ou usar um gateway de API.

Quando o erro envolve credenciais ou preflight

Se a requisição usa cookies ou autenticação, o cabeçalho Access-Control-Allow-Origin não pode ser *. Ele deve refletir a origem exata. Além disso, o servidor precisa responder ao método OPTIONS (preflight) com Access-Control-Allow-Headers e Access-Control-Allow-Methods corretos. Um erro comum é esquecer de tratar o preflight, fazendo a requisição falhar antes mesmo de chegar à rota.

Resumo

O erro CORS é um mecanismo de segurança do navegador, não um bug do seu código. Identifique a origem no console, configure os cabeçalhos no servidor e, em desenvolvimento, use um proxy. Em produção, nunca tente burlar a política; ajuste a API corretamente.

Perguntas frequentes sobre CORS erro

O que significa CORS?

CORS significa Cross-Origin Resource Sharing, ou Compartilhamento de Recursos entre Origens. É um padrão HTTP que permite ao servidor declarar quais origens podem acessar seus recursos, usando cabeçalhos específicos.

Por que o erro CORS só aparece no navegador?

Porque a política de mesma origem é implementada no navegador. Ferramentas como Postman ou cURL não aplicam essa regra, por isso as requisições funcionam fora do navegador. O servidor pode até responder, mas o navegador bloqueia a leitura da resposta.

Posso desativar o CORS no navegador?

Existem extensões que desativam a verificação, mas isso é arriscado e serve apenas para testes locais. Em produção, desativar a política expõe o usuário a ataques de cross-site request forgery e vazamento de dados.

Como resolver CORS em APIs de terceiros?

Se a API não envia o cabeçalho Access-Control-Allow-Origin, você não pode alterar o servidor dela. Nesse caso, crie um proxy próprio no seu backend que faça a requisição e devolva a resposta com os cabeçalhos corretos.

O que é preflight e quando ele ocorre?

Preflight é uma requisição OPTIONS que o navegador envia antes da requisição real, quando o método não é simples (GET, POST com certos content-types) ou quando há cabeçalhos personalizados. O servidor precisa responder a ela com permissão, ou a requisição principal é bloqueada.

Erro CORS pode causar perda de dados?

Não. O bloqueio acontece antes da resposta ser processada pelo front-end. Os dados continuam no servidor; apenas o navegador impede que a aplicação os leia. Isso protege o usuário, mas exige configuração correta para funcionar.