Explicador de Encabezados CORS

El Explicador de Headers CORS proporciona una referencia interactiva y un validador de configuración para los headers de Cross-Origin Resource Sharing, ayudándote a entender, depurar y corregir errores CORS sin ciclos de despliegue de prueba y error. Ingresa tu origen de petición, método y headers personalizados junto con los headers de respuesta CORS del servidor, y ve al instante si el navegador permitiría o bloquearía la petición -- con una explicación clara de por qué.

Entendiendo CORS

Si alguna vez has visto el mensaje "Access to XMLHttpRequest has been blocked by CORS policy" en la consola de tu navegador, has encontrado uno de los mecanismos de seguridad más comunes y confusos de la web. CORS significa Cross-Origin Resource Sharing, y existe para proteger a los usuarios de sitios web maliciosos que intentan hacer peticiones a otros sitios en nombre del usuario. Sin CORS, cualquier página web que visites podría enviar silenciosamente peticiones a la API de tu banco usando tu sesión activa -- CORS previene esto requiriendo que el servidor del banco opte explícitamente por recibir peticiones de otros orígenes.

Un origen se define por la combinación de esquema, host y puerto: https://app.example.com y https://api.example.com son orígenes diferentes aunque compartan el mismo dominio raíz. Cuando tu JavaScript frontend en https://app.example.com hace una petición fetch a https://api.example.com/data, el navegador verifica si el servidor API ha enviado los headers CORS correctos indicando que permite peticiones desde https://app.example.com. Si los headers faltan o son incorrectos, el navegador bloquea la respuesta para que no llegue a tu JavaScript, aunque el servidor realmente procesó la petición y envió datos de vuelta.

La confusión alrededor de CORS viene de su diseño por capas. Las peticiones simples -- GET o POST básicos con headers estándar -- pasan directamente, y el navegador verifica los headers CORS en la respuesta. Pero cualquier petición que use headers personalizados, tipos de contenido no estándar, o métodos como PUT o DELETE dispara una verificación preflight: el navegador envía primero una petición OPTIONS para preguntar al servidor si aceptará la petición real. El servidor debe responder a este preflight con los headers Access-Control-Allow-* correctos antes de que el navegador envíe la petición real. Esta herramienta simula ambos escenarios para que puedas validar tu configuración antes de desplegar.

Cómo verificar una configuración CORS

1. Ingresa el origen de la petición (por ejemplo, https://app.example.com), el método HTTP y cualquier header personalizado que tu frontend envíe.
2. Ingresa los headers de respuesta CORS del servidor (Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc.).
3. Haz clic en Verificar para simular la validación CORS del navegador.
4. Revisa el resultado: la herramienta explica si la petición sería permitida o bloqueada e identifica la razón exacta de cualquier fallo.

Ejemplos de headers CORS

Petición simple (permitida)

Resultado: Permitida. El origen coincide exactamente.

Petición preflight con headers personalizados (permitida)

Resultado: Permitida. El origen, método y headers coinciden. El preflight se almacena en cache por 24 horas.

Petición con credenciales (bloqueada)

Resultado: Bloqueada. Cuando Access-Control-Allow-Credentials es true, el header Access-Control-Allow-Origin no puede ser el comodín * -- debe especificar el origen exacto.

Cuándo usar el explicador de headers CORS

• Depuración de "CORS error" en consolas de navegador -- Pega los detalles de tu petición y los headers del servidor para descubrir exactamente por qué el navegador está bloqueando la petición.
• Configuración de CORS para APIs -- Valida tus headers Access-Control-* antes de desplegar a producción.
• Configuración de headers en CDN o proxy reverso -- Prueba el paso de headers CORS cuando usas CloudFront, Cloudflare o nginx como proxy.
• Entendiendo preflight vs. peticiones simples -- Aprende qué características de la petición disparan una petición OPTIONS preflight.
• Corrección de problemas con credenciales y cookies -- Diagnostica por qué las cookies o los headers Authorization no se envían en peticiones cross-origin.
• Capacitación y documentación -- Usa el verificador interactivo como herramienta de enseñanza para desarrolladores que aprenden CORS por primera vez.

Cómo funciona CORS

Peticiones simples vs. peticiones preflight

Los navegadores clasifican las peticiones cross-origin en dos categorías:

Peticiones simples se envían directamente sin verificación preflight. Una petición es "simple" cuando usa GET, HEAD o POST con solo headers estándar (Accept, Accept-Language, Content-Language, Content-Type limitado a application/x-www-form-urlencoded, multipart/form-data o text/plain).

Peticiones preflight se disparan para cualquier cosa fuera de los criterios de petición simple. El navegador envía primero una petición OPTIONS, y el servidor debe responder con los headers Access-Control-Allow-* apropiados antes de que se envíe la petición real.

Referencia de headers CORS

Errores comunes de CORS

• Configurar Access-Control-Allow-Origin: * con Access-Control-Allow-Credentials: true -- esta combinación está explícitamente prohibida por la especificación.
• Olvidar incluir Content-Type en Access-Control-Allow-Headers al enviar JSON -- application/json no es un tipo de contenido "simple".
• No manejar el método OPTIONS preflight en el servidor, resultando en una respuesta 405 Method Not Allowed.
• Omitir Access-Control-Expose-Headers y preguntarse por qué JavaScript no puede leer los headers de respuesta personalizados.

Flujo de validación CORS

Navegador                                  Servidor
  |                                          |
  |-- ¿Es una petición simple? ------------>|
  |   (GET/HEAD/POST, headers estándar)      |
  |                                          |
  |   SÍ: Enviar petición directamente      |
  |   NO: Enviar OPTIONS preflight primero   |
  |                                          |
  |<--- Respuesta preflight -----------------|
  |   Access-Control-Allow-Origin: ...       |
  |   Access-Control-Allow-Methods: ...      |
  |   Access-Control-Allow-Headers: ...      |
  |                                          |
  |-- Verificar: ¿Coincide el origen? ----->|
  |-- Verificar: ¿Método permitido? ------->|
  |-- Verificar: ¿Headers permitidos? ----->|
  |                                          |
  |   TODO PASA: Enviar petición real        |
  |   ALGO FALLA: Bloquear y registrar error |

Consejos prácticos para la configuración CORS

El enfoque más seguro para la configuración CORS es comenzar con las restricciones más estrictas y abrir solo lo que tu aplicación necesita. Empieza especificando los orígenes exactos que deben tener acceso en lugar de usar *. Si tu frontend está en https://app.example.com, configura Access-Control-Allow-Origin: https://app.example.com explícitamente. Esto previene que cualquier otro sitio haga peticiones cross-origin a tu API. Si necesitas soportar múltiples orígenes, implementa verificación dinámica de origen en el servidor -- lee el header Origin de la petición, verifícalo contra tu lista permitida, y devuélvelo en la respuesta.

El almacenamiento en cache de preflight es una optimización frecuentemente ignorada. Sin Access-Control-Max-Age, el navegador envía una petición OPTIONS preflight antes de cada petición cross-origin. En una aplicación que hace llamadas API frecuentes, esto duplica el número de peticiones. Configurar Access-Control-Max-Age: 3600 (1 hora) le dice al navegador que almacene en cache el resultado del preflight, eliminando peticiones OPTIONS redundantes. Ten en cuenta que la mayoría de los navegadores limitan esto a aproximadamente 7,200 segundos (2 horas), y Chrome lo limita a 2 horas incluso si configuras un valor más alto.

Cuando tu API necesita devolver headers de respuesta personalizados que JavaScript debería leer (como información de paginación en X-Total-Count o IDs de petición en X-Request-ID), debes listarlos en Access-Control-Expose-Headers. Por defecto, JavaScript solo puede leer un pequeño conjunto de headers de respuesta "seguros para CORS": Cache-Control, Content-Language, Content-Type, Expires, Last-Modified y Pragma. Cualquier header personalizado es invisible para tu código frontend a menos que lo expongas explícitamente. Esta es una fuente común de confusión al depurar problemas de paginación o visualización de límites de tasa.

Preguntas frecuentes

¿Por qué mi petición funciona en Postman pero falla en el navegador?

Postman y otros clientes de API no aplican CORS porque CORS es un mecanismo de seguridad exclusivo del navegador. La política del mismo origen es aplicada por el navegador para proteger a los usuarios de scripts maliciosos. Las peticiones servidor a servidor no se ven afectadas por CORS.

¿Puedo usar Access-Control-Allow-Origin: * con cookies?

No. Cuando la petición incluye credenciales (cookies, autenticación HTTP), el servidor debe responder con el origen solicitante exacto, no *. Configura Access-Control-Allow-Origin: https://app.example.com y Access-Control-Allow-Credentials: true juntos.

¿Qué es Access-Control-Max-Age y debería configurarlo?

Le dice al navegador cuánto tiempo almacenar en cache la respuesta preflight. Sin él, el navegador envía una petición OPTIONS antes de cada petición cross-origin. Configurarlo a 86400 (24 horas) reduce significativamente la sobrecarga de preflight. La mayoría de los navegadores lo limitan a 7200 segundos (2 horas) sin importar el valor que configures.

¿Por qué recibo un error CORS aunque el servidor devuelve 200?

CORS es aplicado por el navegador, no por el servidor. El servidor procesa la petición y envía una respuesta 200, pero si la respuesta carece del header Access-Control-Allow-Origin correcto, el navegador bloquea que JavaScript acceda a los datos de la respuesta. La petición tiene éxito del lado del servidor -- simplemente no puedes leer el resultado desde tu frontend.

¿Cómo manejo CORS para conexiones WebSocket?

Las conexiones WebSocket no usan CORS. El handshake HTTP inicial que hace upgrade a WebSocket no está sujeto a preflight CORS. Sin embargo, aún debes validar el header Origin del lado del servidor durante el handshake de WebSocket para prevenir secuestro de WebSocket cross-origin.

¿Puedo usar CORS para restringir qué servidores pueden llamar a mi API?

No. CORS solo restringe peticiones basadas en navegador. Cualquier servidor, script o herramienta de línea de comandos puede llamar a tu API directamente sin restricciones CORS. Para autenticación servidor a servidor, usa API keys, tokens OAuth o TLS mutuo. CORS es específicamente una característica de seguridad del navegador, no un mecanismo de control de acceso general.

Herramientas relacionadas

• HTTP Header Formatter - Analiza y formatea headers HTTP incluyendo headers CORS
• HTTP Status Code Lookup - Busca códigos de estado devueltos durante fallos de preflight
• Cookie Header Parser - Analiza cookies que interactúan con la configuración de credenciales CORS
• curl Command Builder - Construye comandos curl para probar endpoints habilitados con CORS
• MIME Type Lookup - Busca valores de Content-Type que afectan las decisiones de CORS simple vs. preflight