HTTP 401 Unauthorized: qué significa y cómo solucionarlo

Qué significa este error y cómo reconocerlo

• Un navegador, cliente de API, herramienta de monitorización o verificador de sitios web informa de 401 Unauthorized.
• Una página protegida o una ruta de API solicita iniciar sesión, rechaza una sesión o devuelve un cuerpo de error de autenticación.
• El mismo host puede servir correctamente algunas URL públicas mientras una ruta o método de solicitud devuelve 401.
• Una solicitud puede recibir HTTP 401 incluso cuando la resolución DNS y la negociación TLS funcionan.
• Los headers de respuesta pueden identificar los requisitos de autenticación, las redirecciones, el comportamiento de la caché, un proxy o CDN y, en ocasiones, un ID de solicitud o de correlación.
• Las solicitudes realizadas con una sesión del navegador pueden comportarse de forma distinta a las realizadas por un cliente de API o un servicio de monitorización.

Causas principales, ordenadas por probabilidad

1. Autenticación ausente o no válida — La solicitud no contiene credenciales, la sesión ha caducado, el token no es válido, la contraseña es incorrecta o el header de autorización tiene un formato incorrecto.
2. Contexto de solicitud incorrecto — El cliente usa una URL, método HTTP, host, audience, scope, cookie, API key o entorno incorrectos, por lo que las credenciales válidas en otro lugar no se aceptan aquí.
3. Reglas de autenticación de la aplicación — El middleware, los route guards o la validación de sesión rechazan la solicitud antes de que se ejecute el handler de la aplicación.
4. Reglas del servidor web, reverse proxy, CDN o WAF — Una capa de infraestructura requiere autenticación o reenvía credenciales incompletas, modificadas o ausentes.
5. Comportamiento de la caché o del routing — Una respuesta almacenada en caché, una redirección inesperada, una ruta obsoleta o una discrepancia de host/protocolo envía al cliente a un endpoint con requisitos de autenticación diferentes.
6. Cambios en la configuración o en los servicios upstream — Un despliegue, un cambio en el proveedor de identidad, una rotación de secretos, un cambio de proxy o una discrepancia entre entornos hace que fallen solicitudes que antes eran válidas.

Cómo solucionarlo

Para visitantes

1. Verifica la dirección exacta y vuelve a intentarlo una sola vez, sin actualizar la página repetidamente.
2. Si el recurso requiere una cuenta, inicia sesión mediante la interfaz habitual del sitio y vuelve a intentarlo. Comprueba si la sesión ha caducado.
3. Si solo falla un enlace, informa de esa URL concreta en lugar de asumir que todo el sitio no está disponible.
4. Anota la hora aproximada, la página o el endpoint de API y el mensaje 401 mostrado. No envíes contraseñas, cookies, tokens de acceso ni otros secretos.
5. Contacta con el propietario del sitio si una página que normalmente es pública devuelve 401 o si el inicio de sesión funciona, pero el recurso protegido sigue sin estar disponible.

Para clientes de API y desarrolladores

1. Reproduce el fallo con el mismo método HTTP, URL, host, parámetros de consulta, headers y cuerpo que utiliza el cliente que falla. Cuando sea posible, usa una cuenta que no sea de producción o una credencial de prueba.
2. Confirma que la credencial está presente, no ha caducado, tiene el formato correcto y está destinada a este host, ruta y entorno. Comprueba el scope o la audience del token cuando el sistema de autenticación los utilice.
3. Captura el estado, los headers de respuesta y el cuerpo de la respuesta sin exponer secretos. Presta especial atención a la información del challenge de autenticación, las redirecciones, los headers de caché y los IDs de solicitud.
4. Compara una solicitud que sabes que funciona con la solicitud que falla, cambiando una diferencia cada vez. Comprueba las cookies, los headers de autorización, el reenvío del proxy, las redirecciones y el método de solicitud.
5. Identifica el componente que generó la respuesta: aplicación, servidor web, reverse proxy, CDN o WAF. El cuerpo de la respuesta, los headers distintivos y los logs específicos de cada capa pueden ayudar a diferenciarlos.
6. Revisa los logs correspondientes usando la marca de tiempo, la ruta, el cliente y el ID de solicitud. Comprueba los despliegues recientes, los cambios en el proveedor de identidad, la rotación de secretos, las actualizaciones de routing y la configuración del proxy.
7. Aplica la corrección autorizada más específica —por ejemplo, corregir una credencial o una regla de reenvío específica de la ruta— y vuelve a probar la misma solicitud. No desactives la autenticación, no almacenes respuestas privadas en caché de forma pública ni concedas permisos amplios como primera medida.
8. Prueba las rutas públicas y protegidas relacionadas, los métodos HTTP relevantes y el comportamiento previsto sin autenticación para asegurarte de que la corrección no creó un problema de control de acceso.

Distinguir 401 de fallos relacionados

• 401 Unauthorized: la autenticación falta, no es válida o el endpoint no la acepta.
• 403 Forbidden: el servidor entendió la solicitud, pero no autorizará el acceso; aun así puede haber una autenticación válida.
• 404 Not Found: la ruta o el recurso no están disponibles en esa ubicación, aunque algunos sistemas ocultan intencionadamente los recursos protegidos de esta manera.
• Respuesta 5xx: el procesamiento del lado del servidor falló, en lugar de limitarse a rechazar la autenticación.

Prevención y cómo verificar la solución

• Monitoriza los fallos de autenticación por ruta, método, tipo de cliente y despliegue para distinguir un problema aislado de una ruta de un incidente más amplio.
• Mantén bajo control de versiones la configuración de autenticación, routing, proxy y caché, y revisa los cambios antes de publicarlos.
• Prueba las respuestas esperadas sin autenticación, con autenticación y con permisos insuficientes para las rutas web y los métodos de API importantes.
• Usa credenciales y configuración separadas para desarrollo, pruebas y producción; rota los secretos mediante un proceso controlado.
• Evita que los tokens de acceso, las cookies y las contraseñas aparezcan en los logs de la aplicación, el proxy, la monitorización o el soporte.
• Conserva durante el tiempo suficiente los IDs de solicitud anonimizados, las marcas de tiempo y los logs específicos de cada capa para investigar los fallos de autenticación.
• Documenta qué rutas son intencionadamente públicas, protegidas o restringidas según el método y el tipo de cliente.

Preguntas frecuentes