Resolvendo o "CORS error" e problemas comuns de Access-Control-Allow-Origin: Um Guia Completo

Se você já construiu uma aplicação web que faz requisições para uma API em um domínio diferente, quase certamente encontrou o temido "CORS error". Geralmente, ele se parece com isto no console do seu navegador:

Access to fetch at 'https://api.example.com' from origin 'https://myapp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Neste guia, explicaremos exatamente o que é o CORS, por que ele existe e como corrigir esses erros de uma vez por todas.

1. Mensagens comuns de CORS error

Você verá principalmente estes erros nas Ferramentas do Desenvolvedor do seu navegador (aba Console ou Rede):

blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present ...
The 'Access-Control-Allow-Origin' header contains multiple values ...
Response to preflight request doesn't pass access control check ...
Method NOT ALLOWED ... (quando o método HTTP como POST ou DELETE não é permitido pelo CORS)

2. O que é CORS?

CORS (Cross-Origin Resource Sharing) é um recurso de segurança implementado pelos navegadores. Ele evita que um site malicioso faça requisições para um domínio diferente (como seu banco ou sua API privada) sem permissão.

Por padrão, os navegadores seguem a Política de Mesma Origem (Same-Origin Policy), o que significa que um script em a.com só pode solicitar dados de a.com. CORS é o mecanismo que permite que a.com solicite dados com segurança de b.com se b.com permitir explicitamente.

3. Principais causas e soluções

3.1 Cabeçalho "Access-Control-Allow-Origin" ausente

Este é o erro mais comum. Significa que o servidor de onde você está solicitando dados não disse ao navegador que seu domínio tem permissão para acessar o recurso.

A Solução: A correção DEVE acontecer no lado do servidor. Você precisa adicionar o cabeçalho Access-Control-Allow-Origin à resposta.

Para APIs públicas: Defina como * (permitir todos).
Para APIs privadas: Defina como seu domínio específico (ex: https://myapp.com).

3.2 Falhas de CORS preflight

Para requisições "complexas" (como aquelas com cabeçalhos personalizados ou métodos como PUT/DELETE), o navegador envia primeiro uma requisição automática OPTIONS. Isso é chamado de requisição de Preflight (pré-verificação).

O Erro: Response to preflight request doesn't pass access control check.

A Solução: Certifique-se de que seu servidor trate as requisições OPTIONS e retorne um status 200 OK ou 204 No Content com os cabeçalhos CORS corretos:

Access-Control-Allow-Origin
Access-Control-Allow-Methods (ex: GET, POST, OPTIONS, PUT, DELETE)
Access-Control-Allow-Headers (ex: Content-Type, Authorization)

3.3 "Access-Control-Allow-Credentials"

Se você estiver enviando cookies ou cabeçalhos de autorização com sua requisição (withCredentials: true), as regras de CORS tornam-se mais rígidas.

O Erro: The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*' when the request's credentials mode is 'include'.

A Solução:

Você não pode usar * para Access-Control-Allow-Origin. Você deve especificar a origem exata.
Você também deve adicionar o cabeçalho: Access-Control-Allow-Credentials: true.

4. Como corrigir CORS em diferentes ambientes

4.1 Node.js (Express)

A maneira mais fácil é usar o middleware cors:

const express = require('express');
const cors = require('cors');
const app = express();

app.use(cors({
  origin: 'https://myapp.com',
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  credentials: true
}));

4.2 Nginx

Adicione estas linhas ao seu bloco server ou location:

add_header 'Access-Control-Allow-Origin' 'https://myapp.com' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always;

if ($request_method = 'OPTIONS') {
    return 204;
}

4.3 Python (Flask)

Use a extensão flask-cors:

from flask import Flask
from flask_cors import CORS

app = Flask(__name__)
CORS(app, origins=["https://myapp.com"])

5. FAQ: Perguntas Frequentes

P: Posso corrigir um CORS error a partir do frontend (JavaScript)?

R: Não. CORS é uma política de segurança do lado do servidor imposta pelo navegador. Você não pode "contorná-la" em seu código JavaScript. Se você não controla o servidor, deve usar um Servidor Proxy (Proxy Server) para buscar os dados para você.

P: Por que só vejo erros de CORS no navegador e não no Postman?

R: O Postman é um aplicativo independente, não um navegador web. Ele não impõe a Política de Mesma Origem ou as regras de CORS. Apenas navegadores web (Chrome, Firefox, etc.) impõem o CORS.

P: Qual é o risco de definir Access-Control-Allow-Origin como "*"?

R: Para dados públicos, não há risco. No entanto, para uma API que lida com dados de usuário ou requer autenticação, defini-la como * permite que qualquer site faça requisições em nome de um usuário logado, potencialmente levando ao roubo de dados.

6. Tabela resumida de cabeçalhos CORS

Cabeçalho	Descrição
`Access-Control-Allow-Origin`	Especifica quais domínios têm permissão para acessar o recurso.
`Access-Control-Allow-Methods`	Especifica quais métodos HTTP (GET, POST, etc.) são permitidos.
`Access-Control-Allow-Headers`	Especifica quais cabeçalhos personalizados podem ser enviados.
`Access-Control-Allow-Credentials`	Indica se a resposta pode ser compartilhada quando a flag `credentials` é true.
`Access-Control-Max-Age`	Especifica por quanto tempo os resultados de uma requisição preflight podem ser armazenados em cache.

Erros relacionados

Resolvendo erros de 'Unexpected token in JSON'
Como corrigir 'URIError: URI malformed' em JavaScript
Resolvendo 'JWT expired' e erros comuns de JWT

Resolvendo o 'CORS error' e problemas comuns de Access-Control-Allow-Origin