Entendendo CORS: Por Que Sua Requisição Falhou

Quando sua aplicação JavaScript lança um erro de CORS, não é código quebrado—é o navegador protegendo os usuários de potenciais ameaças de segurança. Entender por que esses erros ocorrem requer compreender o modelo de segurança fundamental que governa como os navegadores lidam com requisições entre origens diferentes.

A Base da Política de Mesma Origem

Os navegadores aplicam a Política de Mesma Origem (Same-Origin Policy) como seu mecanismo de segurança primário. Uma origem consiste em três partes: protocolo (https://), domínio (example.com) e porta (:3000). Quando estes correspondem exatamente, as requisições fluem livremente. Quando diferem—mesmo que ligeiramente—você está fazendo uma requisição entre origens diferentes (cross-origin).

Considere estas origens:

• https://app.example.com → https://api.example.com (subdomínio diferente = origem diferente)
• http://localhost:3000 → http://localhost:3001 (porta diferente = origem diferente)
• http://example.com → https://example.com (protocolo diferente = origem diferente)

Sem esta política, qualquer site poderia ler seu Gmail, acessar seus dados bancários ou fazer requisições em seu nome. Cross-Origin Resource Sharing (CORS) fornece um relaxamento controlado dessas restrições.

Como os Navegadores Aplicam CORS

O navegador atua como o executor, não o servidor. Esta distinção é importante porque explica equívocos comuns:

1. “Funciona no Postman/curl” - Essas ferramentas não são navegadores; elas não aplicam CORS
2. “Adicionar modo no-cors vai resolver” - Isso não desabilita CORS; cria uma resposta opaca que você não pode ler
3. “O servidor está bloqueando minha requisição” - O servidor responde normalmente; o navegador bloqueia o acesso à resposta

Quando você faz uma requisição entre origens diferentes, o navegador automaticamente adiciona um cabeçalho Origin. O servidor deve responder com um cabeçalho Access-Control-Allow-Origin que corresponda à sua origem (ou * para recursos públicos). Nenhum cabeçalho correspondente significa que o navegador bloqueia o acesso à resposta—daí seu erro de CORS.

Requisições Simples vs. Requisições Preflight

Nem todas as requisições acionam o mesmo comportamento de CORS. Requisições simples passam imediatamente, enquanto outras requerem uma requisição preflight.

Requisições Simples (Sem Preflight)

Essas requisições atendem TODOS estes critérios:

• Método: GET, HEAD ou POST
• Cabeçalhos: Apenas cabeçalhos simples (Accept, Content-Language, Content-Type)
• Content-Type: Apenas application/x-www-form-urlencoded, multipart/form-data ou text/plain

Requisições que Acionam Preflight

Qualquer requisição que quebre os critérios simples aciona um preflight OPTIONS:

• Métodos como PUT, DELETE, PATCH
• Cabeçalhos personalizados (Authorization, X-API-Key)
• Content-Type: application/json (sim, JSON aciona preflight)

O preflight solicita permissão antes de enviar sua requisição real. O servidor deve responder com cabeçalhos apropriados:

• Access-Control-Allow-Methods (quais métodos são permitidos)
• Access-Control-Allow-Headers (quais cabeçalhos são permitidos)
• Access-Control-Max-Age (por quanto tempo armazenar esta permissão em cache)

Pontos Comuns de Falha de CORS

Cabeçalhos Ausentes ou Incorretos

O servidor não retorna o cabeçalho Access-Control-Allow-Origin, ou ele não corresponde à sua origem. Lembre-se: http://localhost:3000 e http://localhost:3001 são origens diferentes.

Restrições de Credenciais

Incluir credenciais (credentials: 'include' ou withCredentials: true) adiciona restrições:

• O servidor deve incluir Access-Control-Allow-Credentials: true
• Access-Control-Allow-Origin não pode ser *—deve especificar sua origem exata
• Cookies devem atender aos requisitos SameSite

Complicações de Redirecionamento

CORS e redirecionamentos interagem mal. Um redirecionamento para uma origem diferente durante uma requisição CORS frequentemente falha porque o navegador não lida corretamente com a mudança de origem. Evite redirecionamentos entre origens diferentes em requisições CORS.

Acesso a Rede Privada

Navegadores modernos adicionam proteção extra quando sites públicos acessam recursos de rede privada (localhost, 192.168.x.x, 10.x.x.x). Essas requisições podem requerer cabeçalhos adicionais como Access-Control-Allow-Private-Network e acionar preflight mesmo para requisições simples. Esta proteção previne que sites externos escaneiem sua rede local.

Depurando CORS Efetivamente

Ao enfrentar erros de CORS:

1. Verifique a aba Network do navegador - Procure pela requisição preflight OPTIONS e examine os cabeçalhos de requisição e resposta
2. Verifique a mensagem de erro exata - “CORS header ‘Access-Control-Allow-Origin’ missing” vs. “CORS header ‘Access-Control-Allow-Origin’ does not match” apontam para problemas diferentes
3. Teste sem credenciais primeiro - Remova credentials: 'include' para isolar problemas relacionados a credenciais
4. Confirme a correspondência de origem - Garanta que protocolo, domínio e porta correspondam exatamente

Conclusão

Erros de CORS não são obstáculos arbitrários—são o navegador protegendo usuários de requisições maliciosas entre origens diferentes. O servidor declara quais origens podem acessar seus recursos através de cabeçalhos CORS, e o navegador aplica essas regras. Entender este modelo transforma CORS de um bloqueador misterioso em um sistema previsível que você pode depurar metodicamente.

Quando sua requisição falhar, verifique se é uma requisição simples ou preflight, confirme que os cabeçalhos CORS do servidor correspondem exatamente à sua origem e lembre-se que ferramentas como Postman ignoram completamente essas verificações. O navegador está fazendo seu trabalho—sua tarefa é garantir que o servidor forneça as permissões corretas.

Perguntas Frequentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.