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

CORS (Cross-Origin Resource Sharing, ou compartilhamento de recursos entre origens) é um mecanismo de segurança do navegador que define quando uma página pode ler a resposta de um servidor em outro endereço. Quando o servidor não autoriza essa troca, o navegador bloqueia e mostra o famoso erro de origem cruzada no console.

O ponto que mais confunde: o erro aparece no navegador, mas a correção quase sempre é feita no servidor da API. Mexer no código do front-end raramente resolve.

O que é CORS e por que o navegador bloqueia

Tudo parte da política de mesma origem. Uma origem é a combinação de protocolo, domínio e porta. Então https://meusite.com e https://api.meusite.com são origens diferentes, assim como http://localhost:3000 e http://localhost:8000.

Por padrão, um script carregado em uma origem não pode ler respostas de outra. O CORS é a forma de o servidor dizer: “essa origem tem permissão”. Sem esse aval, a requisição pode até chegar ao servidor, mas o navegador não entrega a resposta ao seu código.

Isso vale para navegadores. Ferramentas como curl, Postman ou chamadas feitas de um servidor para outro não aplicam a regra, e por isso a API “funciona” nelas e falha na página.

Como o CORS funciona na prática

A autorização vem em cabeçalhos HTTP da resposta. Os principais são:

• Access-Control-Allow-Origin: informa qual origem pode acessar o recurso.
• Access-Control-Allow-Methods: lista os métodos aceitos, como GET, POST e PUT.
• Access-Control-Allow-Headers: lista os cabeçalhos que o front pode enviar, como Authorization ou Content-Type.
• Access-Control-Allow-Credentials: permite o envio de cookies e credenciais.
• Access-Control-Max-Age: define por quanto tempo o navegador guarda a resposta do preflight.

O que é o preflight

Em requisições mais complexas, o navegador envia antes uma consulta com o método OPTIONS para perguntar se pode fazer a chamada real. Isso acontece, por exemplo, com métodos como PUT e DELETE, com JSON no Content-Type ou com cabeçalhos personalizados como Authorization.

Se o servidor não responder bem a essa consulta, a chamada principal nem é enviada. Muita gente perde tempo olhando o POST quando o problema está no OPTIONS.

Erros comuns e como corrigir

Abra a aba Rede das ferramentas do navegador, localize a requisição que falhou e confira os cabeçalhos da resposta. Em geral, a mensagem do console já indica o que falta. Siga esta ordem:

1. Cabeçalho ausente. Se a mensagem diz que não há Access-Control-Allow-Origin, configure a API para devolvê-lo com a origem do seu front-end.
2. Origem diferente da liberada. Confira protocolo, domínio e porta. Um “http” no lugar de “https” ou uma porta diferente já invalida a correspondência.
3. Preflight falhando. Garanta que o servidor responda ao método OPTIONS com sucesso e inclua os cabeçalhos de permissão. Um redirecionamento ou exigência de login nessa resposta quebra o fluxo.
4. Cabeçalho não permitido. Se o front envia Authorization ou outro cabeçalho personalizado, ele precisa estar em Access-Control-Allow-Headers.
5. Credenciais. Ao enviar cookies, o front precisa ativar o envio de credenciais e o servidor deve liberar Allow-Credentials, além de indicar uma origem específica.

A maioria dos frameworks tem um módulo ou middleware de CORS pronto. Use a documentação oficial do seu framework e liste apenas as origens, métodos e cabeçalhos de que você realmente precisa.

O que evitar

Liberar tudo com o curinga (*) resolve rápido, mas abre a API para qualquer site. Além disso, o navegador não aceita o curinga junto de credenciais. Em produção, prefira uma lista explícita de origens.

Extensões que desativam o CORS e flags para rodar o navegador sem segurança servem, no máximo, para teste local. Elas não corrigem nada para os usuários reais.

Em desenvolvimento, uma alternativa segura é configurar um proxy no servidor de desenvolvimento, para que o front chame a mesma origem e o proxy repasse a requisição à API.

Perguntas frequentes

CORS é um erro do meu código?

Não necessariamente. É uma proteção do navegador que se manifesta como erro quando o servidor não dá permissão. O ajuste costuma ser na configuração da API.

Por que funciona no Postman e não no navegador?

Porque o Postman não aplica a política de mesma origem. Só o navegador bloqueia a leitura da resposta sem os cabeçalhos de CORS.

CORS protege minha API contra acessos indevidos?

Não. Ele protege o usuário no navegador, mas qualquer cliente fora dele pode chamar a API. Autenticação e autorização continuam sendo necessárias.