Debugger de Erros CORS — Ferramenta Online Gratuita

Diagnostique erros de Cross-Origin Resource Sharing e obtenha código de correção pronto para uso em 10 frameworks backend.

O Que é CORS?

Cross-Origin Resource Sharing (CORS) é um mecanismo de segurança do navegador que restringe páginas web de fazer requisições para um domínio diferente do que serviu a página. Quando seu frontend (ex.: https://meuapp.com) faz uma chamada de API para um domínio diferente (ex.: https://api.exemplo.com), o navegador primeiro verifica se o servidor permite explicitamente essa requisição.

Se o servidor não incluir os headers Access-Control-Allow-Origin adequados na sua resposta, o navegador bloqueia a requisição e lança um erro CORS. É importante notar que o CORS é aplicado pelo navegador — a requisição ainda chega ao seu servidor, mas o navegador impede que o JavaScript leia a resposta.

Erros CORS Comuns

  • Header 'Access-Control-Allow-Origin' ausente: A resposta do servidor não contém o header CORS. Correção: adicione o header à resposta do seu servidor.
  • Requisição preflight não passa: Para requisições com headers personalizados ou métodos não simples (PUT, DELETE), os navegadores enviam uma requisição preflight OPTIONS. Seu servidor deve responder corretamente a essa requisição.
  • Flag de credentials: Ao usar cookies ou headers Authorization com withCredentials: true, o servidor deve retornar Access-Control-Allow-Credentials: true e a origem deve ser específica (não *).
  • Incompatibilidade de headers permitidos: Se sua requisição inclui um header não listado em Access-Control-Allow-Headers, o preflight falha.

Como Corrigir CORS Por Framework

Use a ferramenta acima para gerar a correção exata para seu backend. O princípio geral é o mesmo em todos os frameworks: configure seu servidor para retornar os headers Access-Control-Allow-* apropriados. Para produção, sempre especifique as origens permitidas exatas em vez de usar wildcard (*), especialmente ao lidar com requisições autenticadas.

Entendendo o Mecanismo de Preflight CORS

Quando um navegador faz uma requisição cross-origin que não é "simples" (GET/POST com headers básicos), ele primeiro envia uma requisição OPTIONS preflight para pedir permissão ao servidor. Esse processo de duas etapas é a fonte da maioria da confusão com CORS.

O Que Aciona uma Requisição Preflight

  • Headers Personalizados: Qualquer header além de Accept, Content-Type (com valores simples) e Content-Language aciona um preflight. Gatilhos comuns: Authorization, X-Requested-With, X-API-Key
  • Métodos Não Simples: PUT, DELETE, PATCH todos acionam preflights. GET e POST com dados de formulário não.
  • Content-Type além de valores simples: application/json aciona um preflight, enquanto application/x-www-form-urlencoded não. É por isso que fetch com body JSON frequentemente falha quando o mesmo endpoint funciona com dados de formulário.

Checklist de Depuração CORS

Quando encontrar um erro CORS, siga este checklist na ordem:

  • 1. Verifique o console do navegador: A mensagem de erro diz exatamente qual header está faltando ou mal configurado
  • 2. Inspecione a resposta OPTIONS: Abra DevTools → aba Rede → filtre pela requisição falhada → verifique se a resposta OPTIONS inclui os headers corretos Access-Control-Allow-Origin, Access-Control-Allow-Methods e Access-Control-Allow-Headers
  • 3. Verifique se o origin corresponde exatamente: http://localhost:3000 e http://localhost:3001 são origins diferentes. Barras finais também importam.
  • 4. Verifique o modo de credenciais: Se estiver enviando cookies, o servidor deve responder com Access-Control-Allow-Credentials: true E não pode usar curinga (*) para Allow-Origin
  • 5. Verifique se seu proxy não está removendo headers: Proxies reversos (Nginx, Cloudflare, AWS ALB) às vezes removem ou sobrescrevem headers CORS

Erros CORS Comuns em Produção

Os problemas CORS mais frequentes em produção incluem: usar Access-Control-Allow-Origin: * com credenciais (isso falha silenciosamente), esquecer de tratar requisições OPTIONS em funções serverless (Lambda, Vercel), e não incluir Vary: Origin ao configurar dinamicamente o header Allow-Origin (causando problemas de cache CDN). Outro erro comum é corrigir CORS em desenvolvimento mas implantar com uma configuração de proxy diferente que remove os headers.

Perguntas Frequentes sobre CORS

O que causa um erro CORS?

Um erro CORS ocorre quando o navegador bloqueia uma requisição cross-origin porque a resposta do servidor não contém o header Access-Control-Allow-Origin. O navegador aplica a Same-Origin Policy — qualquer requisição de um domínio, porta ou protocolo diferente aciona uma verificação preflight CORS. É importante notar que o CORS é aplicado apenas pelo navegador; a requisição ainda chega ao seu servidor, mas o navegador impede que o JavaScript leia a resposta.

Como corrigir CORS no Express.js?

Instale o pacote cors (npm install cors) e adicione app.use(cors()) para permitir todas as origens, ou especifique origens exatas: app.use(cors({ origin: 'https://seudominio.com' })). Para requisições com cookies ou headers Authorization, defina credentials: true e nunca use wildcard (*) como origem permitida — você deve especificar o domínio exato.

O que é uma requisição preflight CORS?

Um preflight é uma requisição HTTP OPTIONS que o navegador envia automaticamente antes de requisições cross-origin que usam headers personalizados ou métodos HTTP não simples (PUT, DELETE, PATCH). O servidor deve responder ao OPTIONS com os headers Access-Control-Allow-Methods e Access-Control-Allow-Headers, além de um status 200 ou 204. Se o preflight falhar, a requisição real nunca é enviada.

Por que o CORS funciona no Postman mas não no navegador?

O CORS é um mecanismo de segurança do navegador — ele não se aplica a comunicação servidor-para-servidor ou ferramentas como Postman, curl ou clientes REST. O Postman envia requisições diretamente sem aplicar a Same-Origin Policy, então a requisição funciona. No navegador, o JavaScript é impedido de ler respostas cross-origin a menos que o servidor as permita explicitamente via headers CORS.

Ferramentas Relacionadas para Desenvolvedores