4xx · Errores del cliente
Error 401 Unauthorized: qué significa y cómo solucionarlo
El error 401 Unauthorized significa que la petición necesita autenticación y no la lleva, o que las credenciales (usuario y contraseña, token, API key) no son válidas o han caducado. La solución es iniciar sesión de nuevo o enviar un token válido. A pesar del nombre, va de autenticación, no de permisos.
Qué significa el código 401
El nombre es engañoso: "Unauthorized" debería ser "Unauthenticated". El servidor no sabe quién eres, o no se cree quién dices ser. Si sabe quién eres pero no te deja pasar, el código correcto es 403.
Según el estándar, un 401 debe llevar la cabecera WWW-Authenticate indicando cómo autenticarse (Basic, Bearer…). Con Basic, el navegador muestra la ventana de usuario y contraseña.
Causas habituales del error 401
- Token JWT caducado o firmado con otra clave (tras rotar el SECRET_KEY del servidor, todos los tokens antiguos dejan de valer).
- Falta la cabecera Authorization o va mal escrita ("Bearer" sin espacio, comillas de más).
- Contraseña incorrecta en autenticación básica (auth_basic de nginx).
- Cookie de sesión que no se envía: dominio distinto, SameSite estricto o falta withCredentials en peticiones entre dominios.
Si eres visitante de la web
- Cierra sesión y vuelve a entrar.
- Borra las cookies del sitio si el login entra en bucle.
Cómo solucionar el error 401
- Decodifica el JWT y comprueba el campo exp (caducidad) y el emisor.
- Comprueba que el cliente envía exactamente Authorization: Bearer <token>.
- En peticiones entre dominios con cookies, activa credentials en el cliente y Access-Control-Allow-Credentials en el servidor.
- Distingue en tu API entre 401 (no autenticado) y 403 (autenticado sin permiso): facilita mucho la depuración.
Configuración y comandos
Probar una API con token
curl -i https://api.ejemplo.com/perfil -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."nginx: zona protegida con usuario y contraseña
location /privado/ {
auth_basic "Zona privada";
auth_basic_user_file /etc/nginx/.htpasswd; # htpasswd -c /etc/nginx/.htpasswd ana
}Ejemplo de respuesta
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"
Content-Type: application/json
{"detail": "Token caducado"}Herramientas para comprobarlo
Preguntas frecuentes
¿Qué diferencia hay entre el error 401 y el 403?
401: el servidor no sabe quién eres (falta login o el token no vale). 403: sabe quién eres, pero no tienes permiso para ese recurso. Con 401 iniciar sesión lo arregla; con 403, no.
¿Por qué recibo 401 aunque haya iniciado sesión?
Lo más habitual es que la sesión haya caducado, que el token no se envíe en esa petición concreta o que la cookie no viaje por ser de otro dominio.