CORS JavaScript: o que é e como resolver erros

CORS, sigla de Cross-Origin Resource Sharing, é o mecanismo que decide se um JavaScript rodando em uma página pode ler a resposta de uma requisição feita a outro domínio, protocolo ou porta. Quando o console acusa erro de CORS, o bloqueio não vem do seu código: vem do navegador, que exige autorização explícita do servidor de destino. Entender essa divisão de responsabilidades é o primeiro passo para resolver o problema sem tentar burlar a segurança da web.

O que é CORS e por que ele existe

A política de mesma origem (same-origin policy) impede que scripts de um site leiam dados de outro sem permissão. Sem ela, uma página maliciosa poderia fazer requisições autenticadas em seu nome e extrair informações de bancos, e-mails ou redes sociais. O CORS é a válvula de escape: em vez de proibir tudo, permite que o servidor declare quais origens podem acessar seus recursos.

Na prática, o navegador envia a requisição com um cabeçalho Origin. O servidor responde com Access-Control-Allow-Origin. Se os valores não baterem, o navegador entrega a resposta ao JavaScript como erro, mesmo que o servidor tenha respondido com status 200. Esse detalhe confunde muita gente: a requisição chega ao servidor, mas a leitura é bloqueada no cliente.

Quais são os tipos de requisição CORS

Requisições simples usam métodos como GET, HEAD e POST com content-type limitado a application/x-www-form-urlencoded, multipart/form-data ou text/plain. Elas vão direto ao servidor e dependem apenas do cabeçalho de autorização na resposta.

Requisições não simples, como PUT, DELETE ou POST com application/json, disparam uma requisição de verificação prévia chamada preflight. O navegador envia um OPTIONS antes da requisição real, perguntando ao servidor se a operação é permitida. Se o OPTIONS não responder com os cabeçalhos corretos, a requisição principal nem acontece. É por isso que APIs que funcionam no Postman falham no navegador: ferramentas externas não aplicam a política de mesma origem.

Como resolver erro de CORS no servidor

A correção correta acontece no back-end. O servidor precisa incluir cabeçalhos como Access-Control-Allow-Origin, Access-Control-Allow-Methods e Access-Control-Allow-Headers nas respostas. Em APIs públicas, é comum liberar origens específicas em vez de usar o asterisco, porque o curinga não funciona junto com credenciais.

Quando a requisição envia cookies ou tokens, o servidor deve responder com Access-Control-Allow-Credentials: true e uma origem explícita. O front-end, por sua vez, precisa configurar credentials: 'include' no fetch ou withCredentials no XMLHttpRequest. Faltar um dos dois lados mantém o erro, mesmo com os cabeçalhos aparentemente certos.

Em desenvolvimento local, uma alternativa é usar um proxy no servidor de build, como o proxy do Vite ou do webpack-dev-server. Ele faz o navegador acreditar que a requisição é para a mesma origem. Isso resolve o ambiente de teste, mas não substitui a configuração correta em produção.

Por que o erro de CORS aparece mesmo com o servidor respondendo

O navegador esconde detalhes da resposta quando a origem não é autorizada, justamente para não vazar informação. O console mostra uma mensagem genérica, e o status pode aparecer como 0 ou como falha de rede. Antes de culpar o CORS, vale verificar se o servidor está no ar, se o certificado HTTPS é válido e se não há redirecionamento entre HTTP e HTTPS, porque esses fatores também geram mensagens parecidas.

Outro ponto: cabeçalhos duplicados. Se dois middlewares adicionam Access-Control-Allow-Origin com valores diferentes, o navegador rejeita a resposta. Revisar a ordem dos middlewares costuma revelar esse tipo de conflito.

O que não resolve o problema

Desativar a segurança do navegador ou usar extensões que ignoram CORS são paliativos que não devem ir para produção. Eles mascaram o sintoma e podem expor dados do usuário. Da mesma forma, copiar e colar configurações de Allow-Origin: * sem avaliar o contexto pode abrir a API para qualquer site.

A solução durável combina cabeçalhos corretos no servidor, credenciais alinhadas entre front e back e testes com origens reais. Ferramentas de linha de comando ajudam a inspecionar os cabeçalhos, mas a validação final precisa acontecer no navegador, que é quem aplica a política.

Resumo prático

CORS é uma proteção do navegador, não um bug do JavaScript. O erro indica que o servidor não autorizou aquela origem. Corrija no back-end, alinhe credenciais e evite atalhos que desligam a segurança. Assim o front funciona sem abrir mão da proteção do usuário.

FAQ

O que significa CORS em JavaScript?

CORS é o mecanismo que permite requisições entre origens diferentes no navegador. Ele usa cabeçalhos HTTP para o servidor declarar quais domínios podem acessar seus recursos. Sem essa autorização, o JavaScript não consegue ler a resposta, mesmo que a requisição chegue ao destino.

Por que meu fetch funciona no Postman mas falha no navegador?

O Postman não aplica a política de mesma origem. O navegador, sim. Ele verifica os cabeçalhos CORS na resposta do servidor. Se Access-Control-Allow-Origin não corresponder à origem da página, o fetch é bloqueado, independentemente de a API ter respondido corretamente.

Como resolver erro de CORS no front-end?

O front-end sozinho não resolve. A correção principal está no servidor, que deve enviar os cabeçalhos adequados. No cliente, ajuste credentials e o content-type. Em desenvolvimento, um proxy no servidor de build contorna o bloqueio localmente, mas não substitui a configuração de produção.

O que é preflight e quando ele acontece?

Preflight é uma requisição OPTIONS que o navegador envia antes de operações não simples, como PUT, DELETE ou POST com JSON. Ela pergunta ao servidor se a origem e o método são permitidos. Se a resposta não trouxer os cabeçalhos corretos, a requisição real não é enviada.

Posso usar Access-Control-Allow-Origin com asterisco?

Sim, para APIs públicas sem credenciais. O asterisco libera qualquer origem, mas não funciona quando a requisição envia cookies ou tokens. Nesse caso, o servidor precisa informar uma origem específica e definir Access-Control-Allow-Credentials como true.

Erro de CORS pode ser problema de rede?

Pode parecer. Status 0, falha de certificado ou redirecionamento HTTP para HTTPS geram mensagens semelhantes no console. Antes de mexer nos cabeçalhos, confirme se o servidor está acessível e se a URL responde corretamente fora do navegador.