Falta la autenticación o no es válida.
Cuándo usarlo
Sin token o con uno caducado. Pese al nombre, significa “no autenticado”.
Causas habituales y soluciones
Causas habituales: falta la cabecera Authorization o está mal formada, como un token sin el prefijo Bearer, un token de acceso caducado, un token emitido para otro entorno o audiencia, o un desfase de reloj que hace que un JWT parezca caducado o todavía no válido. Decodifica el JWT y comprueba exp, nbf, aud e iss. Un 401 correcto incluye WWW-Authenticate, que indica el esquema que espera el servidor.
Los clientes deberían renovar el token una vez y reintentar, no entrar en un bucle. Las cabeceras se pierden por el camino: los navegadores y curl eliminan Authorization en las redirecciones a otro host, y Apache con PHP-FPM o CGI la elimina a menos que esté definido CGIPassAuth On. Si un preflight CORS falla con 401, tu servidor exige autenticación en OPTIONS; los preflights nunca llevan credenciales, así que déjalos pasar. Usa 403 cuando el usuario es conocido pero no tiene permiso.
Error del cliente (4xx)
Los códigos 4xx son errores del cliente: la solicitud en sí es incorrecta, no está autorizada o apunta a algo que no existe. Repetir la misma solicitud no servirá de nada.
Cómo se ve
HTTP/1.1 401 UnauthorizedCómo enviarlo
| Node.js / Express | res.status(401).end() |
|---|---|
| Python / Flask | return '', 401 |
| nginx | return 401; |
Cómo comprobarlo
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/