Entendiendo CORS: Por Qué Falló Tu Solicitud

Cuando tu aplicación JavaScript arroja un error de CORS, no es código defectuoso—es el navegador protegiendo a los usuarios de posibles amenazas de seguridad. Entender por qué ocurren estos errores requiere comprender el modelo de seguridad fundamental que gobierna cómo los navegadores manejan las solicitudes de origen cruzado.

La Base de la Política del Mismo Origen

Los navegadores aplican la Política del Mismo Origen (Same-Origin Policy) como su mecanismo de seguridad principal. Un origen consta de tres partes: protocolo (https://), dominio (example.com) y puerto (:3000). Cuando estos coinciden exactamente, las solicitudes fluyen libremente. Cuando difieren—incluso ligeramente—estás haciendo una solicitud de origen cruzado.

Considera estos orígenes:

• https://app.example.com → https://api.example.com (subdominio diferente = origen diferente)
• http://localhost:3000 → http://localhost:3001 (puerto diferente = origen diferente)
• http://example.com → https://example.com (protocolo diferente = origen diferente)

Sin esta política, cualquier sitio web podría leer tu Gmail, acceder a tus datos bancarios o hacer solicitudes en tu nombre. Cross-Origin Resource Sharing (CORS) proporciona una relajación controlada de estas restricciones.

Cómo los Navegadores Aplican CORS

El navegador actúa como el ejecutor, no el servidor. Esta distinción importa porque explica conceptos erróneos comunes:

1. “Funciona en Postman/curl” - Estas herramientas no son navegadores; no aplican CORS
2. “Agregar modo no-cors lo arreglará” - Esto no deshabilita CORS; crea una respuesta opaca que no puedes leer
3. “El servidor está bloqueando mi solicitud” - El servidor responde normalmente; el navegador bloquea el acceso a la respuesta

Cuando haces una solicitud de origen cruzado, el navegador automáticamente agrega un encabezado Origin. El servidor debe responder con un encabezado Access-Control-Allow-Origin que coincida con tu origen (o * para recursos públicos). Si no hay un encabezado coincidente, el navegador bloquea el acceso a la respuesta—de ahí tu error de CORS.

Solicitudes Simples vs. Solicitudes Preflight

No todas las solicitudes desencadenan el mismo comportamiento de CORS. Las solicitudes simples pasan inmediatamente, mientras que otras requieren una solicitud preflight.

Solicitudes Simples (Sin Preflight)

Estas solicitudes cumplen TODOS estos criterios:

• Método: GET, HEAD o POST
• Encabezados: Solo encabezados simples (Accept, Content-Language, Content-Type)
• Content-Type: Solo application/x-www-form-urlencoded, multipart/form-data o text/plain

Solicitudes que Desencadenan Preflight

Cualquier solicitud que rompa los criterios simples desencadena un preflight OPTIONS:

• Métodos como PUT, DELETE, PATCH
• Encabezados personalizados (Authorization, X-API-Key)
• Content-Type: application/json (sí, JSON desencadena preflight)

El preflight solicita permiso antes de enviar tu solicitud real. El servidor debe responder con los encabezados apropiados:

• Access-Control-Allow-Methods (qué métodos están permitidos)
• Access-Control-Allow-Headers (qué encabezados están permitidos)
• Access-Control-Max-Age (cuánto tiempo cachear este permiso)

Puntos Comunes de Fallo de CORS

Encabezados Faltantes o Incorrectos

El servidor no devuelve ningún encabezado Access-Control-Allow-Origin, o no coincide con tu origen. Recuerda: http://localhost:3000 y http://localhost:3001 son orígenes diferentes.

Restricciones de Credenciales

Incluir credenciales (credentials: 'include' o withCredentials: true) agrega restricciones:

• El servidor debe incluir Access-Control-Allow-Credentials: true
• Access-Control-Allow-Origin no puede ser *—debe especificar tu origen exacto
• Las cookies deben cumplir con los requisitos de SameSite

Complicaciones con Redirecciones

CORS y las redirecciones interactúan pobremente. Una redirección a un origen diferente durante una solicitud CORS a menudo falla porque el navegador no maneja correctamente el cambio de origen. Evita redirecciones de origen cruzado en solicitudes CORS.

Acceso a Redes Privadas

Los navegadores modernos agregan protección adicional cuando sitios web públicos acceden a recursos de redes privadas (localhost, 192.168.x.x, 10.x.x.x). Estas solicitudes pueden requerir encabezados adicionales como Access-Control-Allow-Private-Network y desencadenar preflight incluso para solicitudes simples. Esta protección previene que sitios web externos escaneen tu red local.

Depurando CORS Efectivamente

Al enfrentar errores de CORS:

1. Revisa la pestaña Network del navegador - Busca la solicitud preflight OPTIONS y examina tanto los encabezados de solicitud como de respuesta
2. Verifica el mensaje de error exacto - “CORS header ‘Access-Control-Allow-Origin’ missing” vs. “CORS header ‘Access-Control-Allow-Origin’ does not match” apuntan a problemas diferentes
3. Prueba sin credenciales primero - Elimina credentials: 'include' para aislar problemas relacionados con credenciales
4. Confirma la coincidencia de origen - Asegúrate de que protocolo, dominio y puerto coincidan exactamente

Conclusión

Los errores de CORS no son obstáculos arbitrarios—son el navegador protegiendo a los usuarios de solicitudes maliciosas de origen cruzado. El servidor declara qué orígenes pueden acceder a sus recursos a través de encabezados CORS, y el navegador aplica estas reglas. Entender este modelo transforma CORS de un bloqueador misterioso en un sistema predecible que puedes depurar metódicamente.

Cuando tu solicitud falla, verifica si es una solicitud simple o preflight, verifica que los encabezados CORS del servidor coincidan exactamente con tu origen, y recuerda que herramientas como Postman omiten estas verificaciones por completo. El navegador está haciendo su trabajo—tu tarea es asegurar que el servidor proporcione los permisos correctos.

Preguntas Frecuentes

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.