CORS sem mistério

Por que o navegador bloqueia a resposta da sua API, como funciona o preflight e como liberar só o necessário.

6 min de leitura · Iniciante · Revisado em

O erro que todo mundo encontra

Console do navegador

Access to fetch at 'https://api.loja.com/pedidos' from origin
'http://localhost:5173' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present.

A requisição chegou ao servidor e ele respondeu. Quem bloqueou foi o navegador, que não entregou a resposta ao seu JavaScript porque o servidor não autorizou essa origem. Por isso o mesmo endpoint funciona no curl, no Postman e no backend, mas falha na página.

Origem e a política de mesma origem

A origem é a combinação de esquema, domínio e porta. Por segurança, o navegador só deixa um script ler respostas da mesma origem da página, a não ser que o outro servidor diga que aceita.

Comparando com a página https://loja.com
EndereçoMesma origem?Motivo
https://loja.com/apiSimSó o caminho muda
http://loja.comNãoEsquema diferente
https://api.loja.comNãoSubdomínio diferente
https://loja.com:8443NãoPorta diferente

Como o navegador pede permissão

Requisições que podem mudar algo, ou que levam cabeçalhos como Authorization e Content-Type: application/json, passam antes por um preflight: uma requisição OPTIONS perguntando se pode.

Um POST com JSON de localhost:5173 para api.loja.com

  1. Navegador → API: OPTIONS /pedidos. Origin: http://localhost:5173 · Access-Control-Request-Method: POST · Access-Control-Request-Headers: content-type, authorization
  2. API → Navegador: 204 No Content. Access-Control-Allow-Origin: http://localhost:5173 · Allow-Methods: GET, POST · Allow-Headers: content-type, authorization
  3. Navegador → API: POST /pedidos. A requisição real, com o corpo JSON.
  4. API → Navegador: 201 Created. Precisa repetir Access-Control-Allow-Origin, senão o navegador esconde a resposta.

Como corrigir

Express com o pacote cors: libere só as origens que você conhece

import cors from 'cors';

const origens = ['https://loja.com', 'http://localhost:5173'];

app.use(
  cors({
    origin: origens,
    credentials: true, // só se usar cookies
  }),
);

No desenvolvimento, o proxy do Vite evita o CORS: tudo vira mesma origem

// vite.config.js
export default {
  server: {
    proxy: { '/api': 'http://localhost:3000' },
  },
};

// no código: fetch('/api/pedidos')
Armadilhas comuns
SintomaCausa provável
Funciona no GET, falha no POSTO servidor não responde ao OPTIONS do preflight
Erro 401 no preflightA autenticação está bloqueando o OPTIONS, que não leva token
Cookies não vão juntoFalta credentials: 'include' no fetch e Allow-Credentials: true no servidor
* com credenciais é rejeitadoCom cookies, a origem precisa ser explícita
Só falha em produçãoA lista de origens não inclui o domínio publicado

Referências

Trilhas relacionadas