O que é CORS web e por que isso importa?
Resposta curta
CORS é um mecanismo baseado em cabeçalhos HTTP que permite ao navegador liberar requisições entre origens diferentes de forma controlada. Ele existe para equilibrar a política de mesma origem com a necessidade de APIs e recursos externos. Sem os cabeçalhos corretos, o navegador bloqueia a leitura da resposta no JavaScript.
Pontos principais
- Origem combina esquema, host e porta.
- O servidor informa permissões por cabeçalhos HTTP.
- Requisições não simples podem disparar um preflight OPTIONS.
- Falhas aparecem no console, não com detalhes no código.
- Credenciais exigem configuração explícita e origem específica.
O que é CORS web é uma pergunta comum quando um front-end chama uma API em outro domínio e o navegador bloqueia a resposta. CORS, ou Cross-Origin Resource Sharing, usa cabeçalhos HTTP para o servidor dizer ao navegador quais origens externas podem acessar um recurso. O navegador aplica a política de mesma origem por padrão e usa esses cabeçalhos para decidir se libera o acesso.
O que é CORS web na prática
Na prática, CORS não é uma configuração do front-end. O navegador envia a requisição e lê os cabeçalhos da resposta; o servidor decide se a origem do site é aceita. Se a resposta não tiver permissão compatível, o JavaScript recebe um erro genérico, mesmo que a requisição tenha chegado ao servidor.
Isso importa porque aplicações modernas separam interface e API. Um site em app.exemplo.com pode precisar ler dados de api.exemplo.com ou de um serviço externo. Sem CORS, o navegador impede a leitura da resposta para proteger dados de outras origens.
Origem, mesma origem e bloqueio padrão
Uma origem é a combinação de esquema, host e porta. https://app.exemplo.com:443 e https://api.exemplo.com:443 são origens diferentes, mesmo com o mesmo domínio principal. O navegador trata essa diferença como fronteira de segurança.
Scripts no navegador seguem a política de mesma origem: por padrão, só leem respostas da origem de onde a página veio, salvo se a outra origem liberar o acesso via CORS.
Incorporar imagens, estilos, scripts, iframes ou vídeos de outra origem costuma ser livre; o bloqueio aparece quando o código tenta ler a resposta, caso em que o navegador exige permissão explícita.
Cabeçalhos que controlam o acesso
O cabeçalho mais conhecido é Access-Control-Allow-Origin. Ele informa quais origens podem ler a resposta. O servidor pode retornar uma origem específica, como https://app.exemplo.com, ou um curinga para recursos públicos.
Outros cabeçalhos definem métodos permitidos, cabeçalhos personalizados e tempo de cache do preflight. Access-Control-Allow-Methods lista verbos como GET, POST, PUT e DELETE. Access-Control-Allow-Headers lista cabeçalhos que o cliente pode enviar. Access-Control-Max-Age indica por quanto tempo o navegador pode reutilizar o resultado do preflight.
Quando credenciais entram na jogada, o servidor usa Access-Control-Allow-Credentials com valor true. Nesse caso, a origem permitida deve ser específica; um curinga não é adequado para respostas com cookies ou autorização. Esse detalhe evita que qualquer site leia dados autenticados.
Resumo dos cabeçalhos principais
| Cabeçalho | Função |
|---|---|
| Access-Control-Allow-Origin | Define a origem que pode ler a resposta |
| Access-Control-Allow-Methods | Lista métodos HTTP permitidos |
| Access-Control-Allow-Headers | Lista cabeçalhos personalizados permitidos |
| Access-Control-Allow-Credentials | Permite envio e leitura com credenciais |
| Access-Control-Max-Age | Cache do resultado do preflight |
Preflight: a requisição OPTIONS antes da real
Para algumas requisições, o navegador envia primeiro uma requisição OPTIONS ao servidor. Esse preflight pergunta se o método e os cabeçalhos da requisição real são permitidos. Se o servidor responder com erro ou sem os cabeçalhos adequados, o navegador não envia a requisição principal.
Disparam o preflight, por exemplo, métodos diferentes de GET, HEAD e POST, cabeçalhos personalizados como X-Auth-Token e Content-Type com valor application/json. Uma chamada fetch com POST, JSON e token costuma gerar duas requisições na aba Network: OPTIONS e depois POST.
O preflight existe porque certas requisições podem alterar dados ou expor informações sensíveis. Ele dá ao servidor a chance de recusar antes da ação principal. Por isso, APIs que aceitam JSON precisam responder corretamente ao OPTIONS, inclusive com status 2xx.
Requisições que não disparam preflight
Há requisições que não disparam preflight. A especificação antiga de CORS as chamava de simples, mas a Fetch spec, que hoje define CORS, não adota esse rótulo. Na prática, isso costuma ocorrer com GET, HEAD ou POST usando tipos de conteúdo considerados simples e sem cabeçalhos personalizados.
Isso não significa ausência de controle. O navegador ainda verifica Access-Control-Allow-Origin na resposta. Se a origem não for permitida, o código não consegue ler o resultado, mesmo sem OPTIONS.
Também é possível que o comportamento mude conforme o navegador. O protocolo CORS exigia esse comportamento, mas depois deixou de exigir; nem todos os navegadores acompanharam a mudança. Em ambientes com navegadores antigos, testes reais são necessários.
Credenciais, cookies e riscos
CORS não substitui autenticação. Ele controla se o navegador permite que uma origem leia a resposta. Se a API usa cookies ou tokens no cabeçalho Authorization, a configuração precisa ser explícita.
No cliente, a requisição precisa indicar que credenciais serão enviadas. No servidor, Access-Control-Allow-Credentials deve ser true e a origem permitida deve ser exata. Combinar credenciais com origem curinga é uma configuração perigosa e incompatível com o comportamento esperado.
Se um site reflete qualquer origem recebida e ativa credenciais, terceiros podem tentar ações privilegiadas ou obter dados sensíveis. Por isso, a lista de origens permitidas deve ser fechada e validada no servidor.
Erros de CORS e como diagnosticar
Em falhas de CORS, o JavaScript só percebe que houve erro, sem detalhes por segurança. Para descobrir a causa, é preciso consultar o console do navegador.
No DevTools, verifique a aba Network. Procure a requisição OPTIONS, o status HTTP, os cabeçalhos enviados e os cabeçalhos retornados. Um erro comum é o servidor não responder ao OPTIONS, retornar 404 ou não incluir a origem correta.
Outro erro comum é configurar o servidor para aceitar qualquer origem enquanto a requisição envia credenciais. Nesse caso, o navegador bloqueia a resposta mesmo com Access-Control-Allow-Origin presente. Ajustar a origem exata costuma resolver.
Boas práticas para APIs e front-end
Configure CORS no servidor, não no navegador. A lista de origens deve ser explícita em produção. Evite curinga em APIs com dados privados e nunca combine curinga com credenciais.
Responda ao OPTIONS com os mesmos cabeçalhos de CORS e um status de sucesso. Se a API usa JSON, inclua application/json em Access-Control-Allow-Headers. Se usa autenticação personalizada, liste o cabeçalho correspondente.
Em desenvolvimento, um proxy do bundler ou do servidor local pode evitar bloqueios temporários, mas não substitui a configuração correta em produção. Teste com origens reais, incluindo portas diferentes, porque localhost:3000 e localhost:5173 são origens distintas.
Se a API usa GraphQL: linguagem de consulta para APIs, o endpoint único ainda segue as mesmas regras de origem. A escolha da tecnologia de backend, discutida em Como escolher uma linguagem de programação para seu projeto, não muda o comportamento do navegador.
Quando CORS pode não ser necessário
Quando um site só incorpora um recurso sem ler seus dados, ou só envia dados para ele, a chance de vazar informações da origem externa é menor e o CORS pode não ser exigido. Mesmo assim, navegadores vêm restringindo mais requisições entre origens, então recursos novos que iniciam requisições costumam exigir CORS.
Isso significa que CORS não é apenas uma barreira para desenvolvedores. Assim, o CORS atua nas APIs do navegador, como fetch e XMLHttpRequest, para reduzir riscos em chamadas entre origens.
Outras perguntas comuns
CORS bloqueia a requisição ou a leitura da resposta?
O navegador pode enviar a requisição, mas bloqueia a leitura da resposta no JavaScript quando os cabeçalhos CORS não permitem a origem. Por isso, o servidor pode ter processado a chamada mesmo com erro no front-end.
Por que aparece uma requisição OPTIONS?
Ela é o preflight. O navegador a envia antes da requisição real para verificar se o método e os cabeçalhos são permitidos pelo servidor.
Posso usar Access-Control-Allow-Origin com curinga em API com login?
Não é recomendado. Com credenciais, a origem deve ser específica e Access-Control-Allow-Credentials deve ser true.
Onde vejo o motivo exato de um erro de CORS?
No console e na aba Network do navegador. O JavaScript recebe apenas um erro genérico por segurança.
Páginas relacionadas
- Renderização no cliente vs servidor: qual a diferença?
A principal diferença na renderização no cliente vs servidor está em onde o HTML é gerado: no navegador ou no servidor. Com SSR, a primeira resposta já traz HTML completo, favorecendo carga inicial e SEO; com CSR, uma estrutura mínima é enviada e o JavaScript monta a interface, favorecendo interatividade. A escolha depende de requisitos de desempenho, visibilidade em buscadores e complexidade da aplicação.
- Cookies web: o que são e como funcionam no navegador
Cookies web são pequenos arquivos de texto enviados por servidores e armazenados no navegador do usuário para reter informações de estado e preferências. Como o protocolo HTTP não guarda memória entre requisições, esses dados permitem identificar usuários autenticados e manter sessões ativas. Eles podem ser temporários ou persistentes, variando conforme a configuração de validade e o domínio de origem.
- Cache web: como funciona e quando limpar
Cache web é o armazenamento temporário de recursos de sites no navegador ou em camadas intermediárias, usado para reabrir páginas mais rápido e reduzir tráfego. Ele não guarda senhas nem configurações pessoais, e costuma se limpar sozinho conforme o espaço disponível.
- WebSocket para serviços especializados: conceito e uso
WebSocket é um protocolo de comunicação que usa uma conexão duradoura entre cliente e servidor para trocar dados nos dois sentidos, sem abrir uma nova requisição HTTP para cada mensagem. Ele é útil em aplicações que precisam de atualizações frequentes e de baixa latência. A escolha depende do volume de mensagens, da necessidade de comunicação nos dois sentidos e da capacidade de operar a conexão.
- GraphQL: linguagem de consulta para APIs
GraphQL é uma linguagem de consulta para APIs e um runtime que executa pedidos contra um schema tipado. O cliente escolhe os campos e relações que precisa, em uma única operação, em vez de depender de endpoints fixos.
- controle pid robotica controle de movimento: guia
Um controlador PID compara a posição ou velocidade desejada de um robô com a medida pelos sensores e calcula uma correção. Ele combina ações proporcional, integral e derivativa para reduzir o erro, compensar desvios acumulados e moderar mudanças bruscas.
Como esta página foi preparada
Antes da redação, o tema foi pesquisado nas fontes abaixo. Depois, a página passou por verificações automáticas de qualidade.