401 Unauthorized: qué significa y cómo solucionarlo

Qué significa 401 Unauthorized

El RFC 9110 define el 401 como una petición que requiere autenticación, ya sea porque no se proporcionó ninguna o porque la que se proporcionó no pasó la comprobación. Una respuesta 401 debe incluir una cabecera WWW-Authenticate que nombre el esquema que espera el servidor, como Basic, Bearer, o Digest. Esa cabecera es la pista que la mayoría de la gente se salta: te dice exactamente qué tipo de credencial quiere el servidor, lo que normalmente es más rápido que adivinarlo.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

Cómo aparece el error

En un navegador, un 401 protegido por autenticación HTTP Basic dispara el aviso nativo de usuario y contraseña, no una página renderizada por el sitio. Un 401 de una API JSON, en cambio, suele aparecer solo en una pestaña de red o en un aviso de error que la propia aplicación construyó para él, ya que no hay una interfaz de navegador por defecto para un fallo de token Bearer. Desde la línea de comandos, tanto la credencial como la cabecera son visibles en una sola petición:

curl -i -H "Authorization: Bearer eyJhbGciOi..." https://api.example.com/v1/account
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="token is expired"

Los registros del servidor y de la aplicación normalmente también registran el motivo, por ejemplo "token expired", "signature invalid", o "no Authorization header", lo que acota la causa más rápido que el código de estado genérico por sí solo.

Qué causa un 401 Unauthorized

Aproximadamente en el orden en que cada uno suele resultar ser la causa:

• No se envió ninguna credencial en absoluto. Una sesión sin iniciar, una clave de API ausente, o un cliente que nunca llegó a adjuntar la cabecera Authorization.
• Un token caducado. Las cookies de sesión, los tokens de acceso OAuth, y los JWT llevan todos un tiempo de vida, y un cliente que usa uno obsoleto recibe 401 aunque funcionara minutos antes.
• Un desajuste de reloj entre el cliente y el servidor. Las reclamaciones exp y nbf de un JWT se evalúan contra el reloj del servidor. Un servidor o cliente con la hora equivocada puede rechazar un token que, según sus propios cálculos, sigue siendo válido, o aceptar uno que ya ha caducado.
• El esquema de autenticación equivocado. Enviar Authorization: Basic ... a un endpoint que espera Bearer, o al revés, falla aunque haya una cabecera presente.
• Una clave de API colocada en el sitio equivocado. Algunas API esperan la clave en una cabecera personalizada como X-API-Key, otras en Authorization, y otras como parámetro de consulta. Poner una clave válida en el sitio equivocado parece idéntico a no enviar ninguna clave.
• Un proxy inverso o gateway que elimina la cabecera Authorization. Algunas configuraciones de proxy y de CDN descartan las cabeceras que no reenvían explícitamente, y una credencial perfectamente válida nunca llega al origen.
• Credenciales revocadas. Un usuario cambió su contraseña, un administrador rotó una clave de API, o un token se invalidó explícitamente al cerrar sesión.

401 frente a 403

Los dos se confunden a menudo porque ambos rechazan la petición, pero la especificación traza una línea clara. Un 401 significa que el servidor necesita que te autentiques, y una credencial válida podría cambiar el resultado; debe llevar WWW-Authenticate. Un 403 significa que el servidor entendió exactamente quién eres y te rechaza de todos modos, por un motivo que la autenticación no puede arreglar, como una restricción de rol o de plan. Si volver a iniciar sesión plausiblemente ayudaría, debería ser 401. Si el usuario ya ha iniciado sesión y simplemente no tiene permiso, debería ser 403, aunque en la práctica muchas API usan 401 de forma laxa para ambos casos.

Cómo saber de quién es la culpa

Si eres tú quien llama a la API, reproduce la petición con una credencial nueva desde un entorno limpio; si un token recién emitido tiene éxito, el antiguo simplemente había caducado o fue revocado. Si un token totalmente nuevo también falla, revisa el esquema y el nombre de la cabecera frente a la documentación de la API antes de asumir que el servidor está roto. Si administras el servicio y los usuarios reportan 401 que no puedes reproducir con tu propia cuenta, la forma más rápida de separar "el servidor está bien, tokens individuales están obsoletos" de "la autenticación en sí está rota para todo el mundo" es ejecutar una comprobación HTTP con una credencial que sabes que funciona desde varias ubicaciones a la vez y comparar los resultados.

Cómo corregir un 401 Unauthorized

Si eres el visitante

1. Vuelve a iniciar sesión. La mayoría de los 401 de una aplicación web son simplemente una sesión caducada, y volver a iniciar sesión la renueva.
2. Revisa el reloj del sistema en tu dispositivo si el mismo inicio de sesión sigue fallando justo después de autenticarte. Un reloj desviado unos minutos puede invalidar tokens basados en tiempo en algunos clientes.
3. Regenera una clave de API o un token desde los ajustes de la cuenta si sospechas que se rotó o se revocó, en lugar de asumir que tu código de integración tiene un fallo.
4. Confirma que la cabecera Authorization realmente se está enviando, usando la pestaña de red de tu navegador o una llamada sencilla con curl, ya que algunas librerías de cliente HTTP descartan en silencio las cabeceras personalizadas en una redirección.

Si administras el sitio

1. Lee la cabecera WWW-Authenticate y tus propios registros para ver el motivo concreto del rechazo antes de cambiar nada; "expired", "invalid signature", y "missing header" apuntan cada uno a una solución distinta.
2. Revisa la sincronización de reloj en los servidores que emiten y validan los tokens. La deriva de NTP en cualquiera de los dos lados es una causa clásica e intermitente de rechazos de JWT que de otro modo parecen aleatorios.
3. Verifica que el proxy o el balanceador de carga reenvía la cabecera Authorization. Una regla añadida por un motivo ajeno puede eliminarla en silencio para cada petición detrás de ese salto.
4. Documenta claramente el esquema y el nombre de cabecera esperados en la documentación de tu API, y devuelve un error_description concreto en la cabecera WWW-Authenticate para que quienes integran no tengan que adivinar.
5. Distingue el 401 del 403 en tus propias respuestas donde importe a quien las llame, para que el código del cliente pueda diferenciar "renueva tu token" de "nunca vas a tener permiso para hacer esto".

Cómo prevenir una caída silenciosa por 401

Un 401 causado por un certificado de firma caducado, un reloj que se desincronizó, o un cambio de proxy que empezó a eliminar la cabecera Authorization no se va a parecer a una caída. El servicio responde al instante y correctamente según sus propias reglas, así que puede quedarse roto para todos los que lo llamen hasta que alguien lo note. Una comprobación HTTP con una aserción sobre el código de estado esperado, ejecutada con una credencial real contra un endpoint autenticado, detecta esto en el momento en que empieza a ocurrir. Para API en concreto, combinar eso con la monitorización de API que comprueba tanto los cuerpos de respuesta como los códigos de estado también detecta un token que se autentica pero devuelve datos mal formados.

Errores relacionados

Consulta 403 Forbidden para peticiones que el servidor entendió y rechazó al margen de las credenciales, la guía de la familia 4xx para la familia más amplia de errores de cliente, y las otras guías de esta tanda: 405 Method Not Allowed, 422 Unprocessable Content.

Preguntas frecuentes

¿Por qué recibo un 401 justo después de iniciar sesión correctamente?

Normalmente por un desajuste de reloj entre tu dispositivo y el servidor, o por un cliente que guardó en caché el token antiguo, ya inválido, en lugar de usar el recién emitido. Confirma que la hora de tu sistema es correcta y que el token nuevo realmente se está enviando.

¿Un 401 significa que hackearon mi cuenta?

No por sí solo. Casi siempre significa una sesión caducada, una clave revocada, o una cabecera enviada de forma incorrecta. Trátalo como un problema de seguridad solo si no esperabas que la credencial dejara de funcionar y no puedes explicar por qué lo hizo.

¿Cuál es la diferencia entre un 401 y un fallo de autenticación en la capa TLS?

Un fallo de certificado de cliente TLS impide que la conexión llegue a establecerse en absoluto, así que nunca se devuelve ningún código de estado HTTP. Un 401 significa que la conexión tuvo éxito y el servidor recibió una petición HTTP completa, y luego la rechazó en la capa de aplicación por no tener credenciales válidas.

¿Debería un propio formulario de inicio de sesión devolver alguna vez 401?

No. Un endpoint de inicio de sesión que evalúa un usuario y una contraseña no está autenticando una petición existente; una contraseña equivocada ahí es convencionalmente un 400 o un 200 con un cuerpo de error, ya que todo el propósito del endpoint es aceptar intentos sin autenticar y juzgarlos.

¿Puede una clave de API válida seguir produciendo un 401?

Sí, si se envía en la cabecera equivocada o con el esquema equivocado, si se rotó después de que tu integración guardara en caché la antigua, o si la petición llegó al servidor a través de un proxy que eliminó la cabecera antes de reenviarla.