CORS: o que é e como corrigir erros de origem cruzada

CORS (Cross-Origin Resource Sharing, ou compartilhamento de recursos entre origens) é um mecanismo dos navegadores que decide se uma página pode ler a resposta de um servidor que está em outra origem. Quando o servidor não autoriza, o navegador bloqueia o acesso e mostra no console o famoso erro de origem cruzada.

A correção quase sempre está no servidor da API, não no código do front-end. Ele precisa responder com os cabeçalhos HTTP certos, dizendo quais origens, métodos e cabeçalhos são aceitos.

Como o CORS funciona

Por padrão, os navegadores seguem a política de mesma origem. Uma origem é a combinação de protocolo, domínio e porta. Por isso https://meusite.com e https://api.meusite.com são origens diferentes, assim como http://localhost:3000 e http://localhost:8080.

O CORS abre exceções controladas a essa regra. O front-end faz a requisição, o navegador envia o cabeçalho Origin e o servidor responde com Access-Control-Allow-Origin, indicando quem pode ler o conteúdo. Se a origem não estiver autorizada, a resposta chega ao navegador, mas o seu JavaScript não consegue acessá-la.

O que é a requisição preflight

Em chamadas mais complexas, o navegador faz antes uma requisição de verificação com o método OPTIONS. Isso acontece, por exemplo, com métodos como PUT e DELETE, com cabeçalhos personalizados (como Authorization) ou com envio de JSON em Content-Type: application/json. Só se o servidor aprovar essa verificação a requisição real é enviada.

Erros de CORS mais comuns

A mensagem varia entre navegadores, mas os casos se repetem:

• No ‘Access-Control-Allow-Origin’ header is present: o servidor não enviou o cabeçalho, ou enviou só em algumas rotas.
• Preflight sem sucesso: a resposta ao OPTIONS veio com erro, redirecionamento ou sem os cabeçalhos de permissão.
• Método ou cabeçalho não permitido: faltam Access-Control-Allow-Methods ou Access-Control-Allow-Headers na resposta.
• Credenciais com curinga: a requisição envia cookies, mas o servidor responde com * em vez de uma origem específica.

Um detalhe que confunde muita gente: se a API cai com erro 500 ou retorna 404 sem os cabeçalhos de CORS, o navegador mostra erro de CORS mesmo assim. Vale olhar a aba Rede das ferramentas do navegador para ver o status real.

Como corrigir no servidor

O ajuste é feito na aplicação ou no servidor web que entrega a API. A maioria dos frameworks (Express, Django, Spring, ASP.NET, Laravel e outros) tem um módulo ou configuração própria para CORS, que costuma ser mais seguro do que montar os cabeçalhos na mão. Consulte a documentação oficial do seu framework para a sintaxe exata.

Em qualquer tecnologia, o roteiro é o mesmo:

1. Liste as origens que realmente precisam acessar a API, como o domínio do seu front-end.
2. Devolva essa origem em Access-Control-Allow-Origin.
3. Responda ao OPTIONS com status de sucesso, incluindo Access-Control-Allow-Methods e Access-Control-Allow-Headers.
4. Se usar cookies ou autenticação por sessão, envie Access-Control-Allow-Credentials: true e use uma origem explícita, sem curinga. No front-end, a requisição também precisa pedir o envio de credenciais.
5. Teste de novo com o cache do navegador limpo, porque o resultado do preflight pode ficar guardado por um tempo.

Soluções que parecem boas, mas não são

Liberar tudo com * resolve o erro em desenvolvimento, mas em produção deixa a API aberta a qualquer site. Use isso apenas em recursos realmente públicos.

O modo no-cors do fetch também não é correção. Ele só faz o navegador enviar a requisição e entrega uma resposta opaca, que o código não consegue ler. Extensões que desativam o CORS no navegador servem, no máximo, para um teste local, e não mudam nada para os outros usuários.

Alternativas em desenvolvimento

Se você não controla a API, uma saída é fazer a chamada pelo seu próprio back-end, que não sofre restrição de CORS, e repassar o resultado ao front-end. Em desenvolvimento local, muitas ferramentas de build também oferecem um proxy que encaminha as requisições e faz o navegador enxergar tudo como mesma origem.

Ao depurar, lembre que ferramentas como Postman e o curl não aplicam CORS. Se a chamada funciona por elas e falha no navegador, o problema está nos cabeçalhos da resposta.

Perguntas frequentes

CORS é um problema de segurança do servidor ou do navegador?

É uma proteção aplicada pelo navegador, mas configurada pelo servidor. Ela não substitui autenticação nem autorização na API.

Por que o erro só aparece no navegador?

Porque só o navegador aplica a política de mesma origem. Servidores, Postman e curl recebem a resposta normalmente.

Posso corrigir o CORS só pelo front-end?

Não. Sem os cabeçalhos corretos na resposta do servidor, nenhuma mudança no JavaScript libera o acesso. A exceção é usar um proxy ou o seu próprio back-end como intermediário.