O que é CORS e por que o navegador bloqueia uma requisição à sua API?
Publicado em 2026-10-20 por frfrand
Qué es CORS, cómo funciona el preflight OPTIONS, diferencia con autenticación y cómo configurarlo sin permitir cualquier origen.
CORS é um mecanismo do navegador que controla quando o código de uma página pode ler respostas procedentes de outra origem. Suas siglas significam Cross-Origin Resource Sharing. Se um frontend em app.ejemplo.com tentar consultar uma API em api.ejemplo.com, o CORS pode entrar em jogo porque as origens são distintas.
Não é uma falha da Internet nem um sistema de autenticação. É uma política relacionada ao navegador e à segurança entre sites.
O que significa origem?
Em uma página da web, a origem é definida por esquema, nome do host e porta. https://ejemplo.com e http://ejemplo.com não têm a mesma origem. Tampouco https://ejemplo.com e https://api.ejemplo.com.
Essa distinção existe para que qualquer página não possa ler livremente dados de outros sites onde uma pessoa tenha sessões abertas.
Um exemplo cotidiano
Imagine que você está dentro do seu banco em uma guia e abre um site desconhecido em outra. Seria perigoso que esse segundo site pudesse consultar automaticamente os detalhes da sua conta e ler a resposta apenas porque o seu navegador tem uma sessão do banco.
O navegador aplica a política de mesma origem e permite certas exceções controladas por meio do CORS. O servidor decide quais origens autoriza a ler determinadas respostas.
O que o servidor faz?
Uma resposta pode incluir Access-Control-Allow-Origin para indicar qual origem está permitida. Por exemplo, uma API destinada a um único frontend poderia autorizar expressamente https://app.ejemplo.com.
Nem sempre corresponde utilizar *. Se a API enviar dados privados ou depender de credenciais, a configuração deve ser muito mais específica. Além disso, existem regras especiais para requisições com credenciais.
CORS não substitui os controles de acesso do backend. Um cliente que não seja um navegador pode chamar diretamente uma API, mesmo sem enviar o cabeçalho Origin.
O que é um preflight OPTIONS?
Em certas requisições, o navegador consulta primeiro se a operação está permitida, normalmente por meio de uma solicitação HTTP OPTIONS. Essa verificação prévia é chamada de preflight.
Pode ocorrer, por exemplo, quando o frontend precisa enviar determinados cabeçalhos personalizados ou métodos. O servidor deve responder com informações compatíveis sobre métodos e cabeçalhos permitidos.
Um erro comum é configurar corretamente uma rota POST, mas esquecer que o servidor ou proxy deve atender ao preflight. Do navegador, parece que a API está fora do ar, embora responda perfeitamente de outra ferramenta.
Como investigar um erro de CORS?
Primeiro, abra as ferramentas de desenvolvedor do navegador e veja a requisição que falhou, sua origem, seus cabeçalhos e a resposta. Verifique se houve uma chamada OPTIONS prévia.
Depois verifique a configuração do backend e de qualquer proxy intermediário. Não comece adicionando cabeçalhos duplicados no Nginx e na aplicação sem saber qual das duas camadas vai gerenciá-los.
Outro erro é instalar uma extensão que desativa temporariamente restrições do navegador e assumir que já corrigiu a aplicação. Isso apenas oculta o sintoma na sua máquina.
CORS não protege sua API de uso abusivo
Embora um site não autorizado não possa ler determinadas respostas por meio de JavaScript do navegador, sua API ainda precisa de autenticação, autorização, validação, limites de tráfego e proteção adequada contra ataques web.
O CORS não impede por si só que alguém chame um endpoint público a partir de um script de servidor.
O que acontece com o ArduMaker?
Se você implantar um frontend e um backend em domínios distintos no ArduMaker, precisará definir quais origens podem consumir sua API a partir de um navegador. Configurá-lo corretamente na aplicação costuma ser mais seguro do que permitir indiscriminadamente qualquer origem.
Em uma frase: O CORS controla certas leituras entre origens realizadas por navegadores. O erro não se resolve «desligando a segurança», mas autorizando as origens necessárias e verificando como o servidor responde.
Fontes: CORS no MDN · Política de mesma origem.