CORS Explicado Como depurar erros de origem cruzada sem perder o controle

Você fez uma requisição fetch. A aba de rede mostra que ela foi disparada. Mas no console há uma parede de vermelho: O acesso ao fetch em 'https://api.example.com' a partir da origem 'https://yourapp.com' foi bloqueado pela política CORS.

Antes de mergulhar nas explicações — aqui está o caminho mais rápido para diagnóstico. Abra DevTools → aba de rede → encontre a requisição falhada → veja os Cabeçalhos de Resposta. Se você não vê Access-Control-Allow-Origin, seu servidor não está enviando cabeçalhos CORS. Isso é a correção. O restante deste artigo explica exatamente o que enviar e por que.

O que é realmente o CORS

CORS — Compartilhamento de Recursos entre Origens — é imposto pelo navegador, não pelo seu servidor. Seu API não bloqueia automaticamente requisições de origens diferentes. O navegador faz isso, em nome dos usuários, para impedir que scripts em evil.com leiam silenciosamente seus dados bancários.

O navegador verifica: "A resposta desse API me diz que é permitido para essa origem ler isso?" Se não, ele bloqueia a resposta — mesmo que o servidor já tenha processado a requisição e retornado um 200. O servidor nunca sabe por que o cliente descartou a resposta.

Isso importa ao fazer depuração: o erro sempre está no lado do cliente. O servidor precisa dizer ao navegador "sim, essa origem é permitida". Isso é o que os cabeçalhos de resposta CORS fazem.

Requisições Simples vs Requisições Preflight

Não todas as requisições entre origens se comportam da mesma forma. O navegador distingue dois tipos.

Requisições simples são requisições GET ou POST com corpos em texto simples ou codificados em formulário e um conjunto pequeno de cabeçalhos permitidos. O navegador as envia diretamente e verifica a resposta para Access-Control-Allow-Origin.

Requisições Preflight ocorrem primeiro quando sua requisição não atende a essas condições — por exemplo, quando você envia um PUT ou DELETE, inclui um cabeçalho personalizado como Authorization ou Content-Type: application/jsonou envia credenciais. O navegador dispara automaticamente uma requisição OPTIONS para a mesma URL antes da sua requisição real. Se o servidor não responder a essa OPTIONS chamada com os cabeçalhos CORS corretos, sua requisição real nunca sai.

Se você está vendo OPTIONS requisições na aba de rede que retornam 404 ou 405, é por isso que suas requisições estão falhando. Seu servidor precisa lidar com OPTIONS para cada rota que recebe tráfego de origens diferentes.

Os Cabeçalhos que Importam

Obter a correção dos cabeçalhos CORS significa entender o que cada cabeçalho de resposta realmente controla:

• Access-Control-Allow-Origin — quais origens podem ler a resposta. Ou seja, uma origem específica (https://yourapp.com) ou * para qualquer origem.
• Access-Control-Allow-Methods — quais métodos HTTP são permitidos (por exemplo, GET, POST, PUT, DELETE, OPTIONS).
• Access-Control-Allow-Headers — quais cabeçalhos de requisição o navegador é permitido enviar (por exemplo, Authorization, Content-Type).
• Access-Control-Allow-Credentials — se cookies e cabeçalhos de autenticação podem ser enviados com a requisição. Deve ser true especificamente.
• Access-Control-Max-Age — por quanto tempo em segundos o navegador deve cachear a resposta do preflight.

A Armadilha do Wildcard

Usar Access-Control-Allow-Origin: * é a forma mais rápida de abrir seu API — mas quebra assim que você adiciona credenciais. Quando Access-Control-Allow-Credentials: true é exigido, o wildcard é rejeitado pelo navegador. Você deve especificar a origem exata:

# This will fail with credentials:
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

# This works:
Access-Control-Allow-Origin: https://yourapp.com
Access-Control-Allow-Credentials: true

Se você tem múltiplas origens permitidas, leia o cabeçalho de origem da requisição e reflita-o condicionalmente — não concatene-os. Origin Erros Comuns de CORS e O Que Eles Significam

A mensagem de erro do navegador geralmente diz exatamente o que está faltando. Aqui está uma referência rápida:

Mensagem de erro

O que significa	Como corrigir	Não há cabeçalho 'Access-Control-Allow-Origin'
O servidor enviou nenhum cabeçalho CORS em absoluto	para a resposta	Adicionar Access-Control-Allow-Origin O valor do cabeçalho 'Access-Control-Allow-Origin' … não corresponde à origem fornecida
Desalinhamento de origem — servidor retornou origem errada ou wildcard com credenciais	Refletir condicionalmente o cabeçalho de origem da requisição; remover wildcard quando usar credenciais	O método PUT não está permitido por Access-Control-Allow-Methods
O método HTTP não está listado no cabeçalho de métodos permitidos	Adicione o método faltante a	O cabeçalho de requisição 'Authorization' não está permitido por Access-Control-Allow-Headers Access-Control-Allow-Methods
O cabeçalho personalizado está faltando na lista permitida	Adicione o cabeçalho a	A resposta à requisição preflight não passa pela verificação de acesso controlado Access-Control-Allow-Headers
A requisição OPTIONS retornou um status incorreto ou faltou cabeçalhos	Trate explicitamente a requisição OPTIONS; retorne 200/204 com os cabeçalhos corretos	Credencial não é suportada se o cabeçalho CORS 'Access-Control-Allow-Origin' for '*'
Wildcard usado com modo de credenciais	Substitua	por origem específica; adicione * Como configurar CORS em Express, FastAPI e Nginx Access-Control-Allow-Credentials: true

Express (Node.js)

FastAPI (Python)

const cors = require('cors');

app.use(cors({
  origin: 'https://yourapp.com',
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
  maxAge: 86400
}));

// Handle preflight for all routes
app.options('*', cors());

Nginx

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourapp.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Observe o padrão do Nginx: você precisa

location /api/ {
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' 'https://yourapp.com';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
        add_header 'Access-Control-Allow-Credentials' 'true';
        add_header 'Access-Control-Max-Age' 86400;
        add_header 'Content-Length' 0;
        return 204;
    }

    add_header 'Access-Control-Allow-Origin' 'https://yourapp.com';
    add_header 'Access-Control-Allow-Credentials' 'true';

    proxy_pass http://backend;
}

em ambos o add_header bloco e o bloco principal. Cabeçalhos definidos dentro do OPTIONS bloco não são passados para o bloco externo. if Seu checklist de depuração

Quando você encontra um erro CORS, siga esta sequência:

Leia a mensagem de erro completa

1. — ela diz exatamente qual cabeçalho ou valor está errado. Verifique a aba de rede
2. — olhe para os cabeçalhos de resposta reais, não para o que você acredita ter configurado. Verifique se há uma requisição OPTIONS
3. — se ela está falhando ou ausente, seu servidor não está lidando com o preflight. Verifique se a origem corresponde exatamente
4. — barras finais, HTTP vs HTTPS e números de porta importam. Remova o wildcard se você estiver usando credenciais
5. — eles são mutuamente exclusivos. Confirme que os cabeçalhos não são removidos por um proxy
6. — Nginx e CDNs às vezes removem ou sobrescrevem cabeçalhos CORS. Uma armadilha fácil de ignorar: se seu API está atrás de um proxy reverso ou CDN, essa camada pode adicionar seu próprio

cabeçalho que conflita com o que seu servidor retorna. Quando dois desses cabeçalhos aparecem em uma única resposta, o navegador rejeita tudo. Sempre verifique os cabeçalhos brutos na camada de rede — não apenas o que seu código de aplicação emite. Access-Control-Allow-Origin Outro caso limite: algumas frameworks só anexam cabeçalhos CORS a rotas que correspondem a um manipulador registrado. Se você estiver atingindo um 404 ou uma rota não registrada, o middleware CORS pode nunca ser executado, e você verá o erro "nenhum cabeçalho presente" mesmo que sua configuração esteja correta. Teste com um endpoint válido primeiro.

Se você precisar gerar rapidamente os cabeçalhos CORS exatos que seu servidor deve retornar, o

IO Tools CORS Headers Builder você pode configurar origem, métodos e credenciais e obter o bloco de cabeçalhos correto pronto para colar na configuração do servidor. Uma nota sobre segurança

O CORS não é um mecanismo de segurança de API. Definir

não torna seu API público de forma significativa — curl, Postman e chamadas entre servidores nunca estão sujeitos a restrições CORS. Apenas chamadas feitas por JavaScript no navegador estão sujeitas. Se sua API precisa de autenticação, enforce-a no nível da API com tokens ou sessões. Os cabeçalhos CORS apenas dizem aos navegadores quais origens são permitidas para ler respostas de JavaScript. Eles são ortogonais ao controle de acesso real. Access-Control-Allow-Origin: * Com esse contexto, você pode tomar decisões sensatas sobre sua configuração CORS, em vez de fechar tudo para uma preocupação mal colocada com segurança ou abrir tudo sem entender o custo.

CORS Explicado: Como Depurar Erros de Origem Cruzada Sem Perder o Controle 2

Você também pode gostar