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

¿Qué es un error 401 Unauthorized?

Un error 401 Unauthorized significa que el servidor necesita que demuestres quién eres, y tu solicitud no lo hizo o las credenciales que llevaba fueron rechazadas. Sin contraseña, con una contraseña incorrecta, con un token expirado o sin clave de API: todo acaba igual.

El estándar HTTP lo define como una solicitud que "carece de credenciales de autenticación válidas para el recurso de destino", y un servidor que envía un 401 DEBE incluir un header WWW-Authenticate que indique qué esquema de inicio de sesión acepta (RFC 9110 §15.5.2).

En términos simples, el servidor te pregunta "¿quién eres?" antes de dejarte entrar.

Cómo se ve un error 401

La página que ves depende del servidor y de la aplicación:

• 401 Unauthorized — la línea de estado estándar y el texto de la mayoría de las aplicaciones
• 401 Authorization Required — el título de la página 401 integrada de nginx, con "nginx" (normalmente con su versión) debajo (código fuente de nginx); los servidores Apache 2.2 antiguos usan las mismas palabras
• Unauthorized · This server could not verify that you are authorized to access the document requested — la página por defecto de Apache
• 401 - Unauthorized: Access is denied due to invalid credentials — IIS; la página detallada (que solo se muestra en el propio servidor) y el registro de IIS dan el motivo como 401.1, 401.2 o 401.3: fallo de inicio de sesión, configuración del servidor o permisos de archivo
• Un cuadro de inicio de sesión en el navegador — cuando el servidor pide autenticación HTTP Basic o Digest, o (en IIS y en intranets de empresa) NTLM o Negotiate
• This page isn't working · HTTP ERROR 401 — Chrome, cuando la respuesta 401 no trae página propia
• JSON de una API, como {"error":{"message":"Missing Authentication header","code":401}}

Los navegadores solo muestran el cuadro de inicio de sesión para esos esquemas. Las API con tokens ("Bearer") nunca lo activan: su 401 llega como JSON para que la aplicación lo gestione. Los sitios con formulario de login suelen enviar al visitante sin sesión a la página de acceso con una redirección 302 en lugar de un 401.

"401 Authorization Required" en nginx

Ese título viene de la página 401 integrada de nginx. Aparece cuando una ubicación está protegida con auth_basic y la solicitud no llevaba usuario y contraseña, o llevaba unos incorrectos; si cancelas el cuadro de inicio de sesión del navegador, también ves esta página.

Como visitante, recarga e introduce el usuario y la contraseña que te dio el propietario del sitio. Son independientes de cualquier cuenta del sitio: la autenticación Basic comprueba un archivo de contraseñas del servidor.

Como propietario del sitio, así se configura la protección y así se deja pública una ruta:

# Create the password file (htpasswd comes with apache2-utils or httpd-tools)
#   sudo htpasswd -c /etc/nginx/.htpasswd alice   # -c creates the file: leave it out when adding users

location /admin/ {
    auth_basic           "Admin area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

# Inside a protected server block, open one path to everyone
location /public/ {
    auth_basic off;
}

# Test, then reload
#   curl -I -u alice:PASSWORD https://example.com/admin/
#   sudo nginx -t && sudo systemctl reload nginx

¿Sigue el 401 con la contraseña correcta? Comprueba que el usuario está en el archivo (htpasswd -c sobrescribe el archivo y elimina a los usuarios anteriores) y que la aplicación que hay detrás de nginx no necesita también el header Authorization: el login Basic de nginx y los tokens Bearer de una aplicación usan el mismo header, así que la aplicación recibe las credenciales de nginx y las rechaza.

401 vs 403: ¿cuál es la diferencia?

Los códigos 401 y 403 se confunden a menudo. En resumen: 401 significa "no sé quién eres", mientras que 403 significa "no te dejo entrar", sea o no la identidad el problema.

Una regla práctica: si proporcionar el usuario y la contraseña correctos (o la clave de API) lo solucionaría, el servidor debería devolver 401. Si el usuario ya está autenticado pero simplemente no tiene acceso a ese recurso, el servidor debería devolver 403 Forbidden.

Causas comunes del error 401

Las causas, desde el lado del visitante hasta el del servidor:

• Usuario o contraseña incorrectos — la causa más básica, sobre todo después de restablecer la contraseña
• Token de autenticación expirado — los tokens JWT, los tokens de acceso OAuth y las cookies de sesión tienen fecha de caducidad
• Header Authorization ausente — la solicitud no incluyó ninguna credencial
• Clave de API inválida — la clave fue revocada, rotada o copiada mal
• Esquema de autenticación incorrecto — el servidor espera un token Bearer pero recibió Basic, o al revés
• Desfase de reloj (clock skew) — el servidor que valida un JWT y el que lo emitió (o tu equipo, si es el que firma el JWT) no coinciden en la hora; muchas bibliotecas no admiten ningún margen
• Un CORS preflight — la comprobación OPTIONS del navegador nunca lleva credenciales, así que un servidor que las exige responde 401 y la solicitud real no llega a enviarse
• Una sesión caducada — el navegador envía una cookie de sesión que el servidor ya cerró
• Algo por el camino elimina el header — Apache oculta Authorization a PHP-FPM y a los scripts CGI si no se le indica lo contrario, CloudFront lo elimina por defecto de las solicitudes GET y HEAD, y la autenticación Basic de nginx delante de una aplicación se lo apropia
• Credenciales bloqueadas o revocadas — demasiados intentos fallidos pueden bloquear una cuenta (algunas API responden entonces con 429 Too Many Requests)

Cómo solucionar el error 401 como visitante

Si encuentras un error 401 en un sitio web al que intentas acceder, el problema casi siempre está relacionado con tus credenciales de inicio de sesión. Sigue estos pasos en orden.

1. Verifica tus credenciales de inicio de sesión

La causa más común de un error 401 es simplemente credenciales incorrectas. Si el sitio muestra una ventana emergente o formulario de inicio de sesión, verifica tu nombre de usuario y contraseña.

Errores comunes: Bloq Mayús está activado, estás usando una contraseña antigua (especialmente después de un restablecimiento reciente), o estás iniciando sesión en la cuenta incorrecta. Si tienes un gestor de contraseñas, deja que complete automáticamente las credenciales para evitar errores de escritura.

2. Limpia la caché y las cookies del navegador

Puede que tu navegador esté enviando una cookie de sesión expirada. Si borras las cookies del sitio, te pedirá iniciar sesión de nuevo.

En Chrome en español, abre "Eliminar datos de navegación" con Ctrl+Mayús+Supr (Cmd+Mayús+Supr en Mac), elige el periodo "Desde siempre" en lugar de "Última hora", marca "Cookies y otros datos de sitios" y "Archivos e imágenes almacenados en caché" y pulsa "Eliminar datos". Esto cierra tu sesión en todos los sitios. Para borrar solo un sitio: Más → Configuración → Privacidad y seguridad → Cookies de terceros → "Ver todos los datos y permisos de sitios", busca el nombre del sitio y pulsa Eliminar. Los pasos para otros navegadores (con los nombres en inglés):

Chrome, Edge, Firefox: Ctrl+Shift+Delete (Cmd+Shift+Delete on a Mac)
  → Time range: All time → Cookies and site data + Cached files → Delete / Clear
  (this signs you out of every site; the per-site option below doesn't)
Safari: Settings → Privacy → Manage Website Data → the site → Remove
One site in Chrome: the icon left of the address → Site settings → Delete data

Tras borrar, cierra el navegador por completo (no solo la pestaña), vuelve a abrirlo y ve de nuevo a la página. Deberías ver una solicitud de inicio de sesión nueva.

3. Prueba en modo incógnito o privado

Abre la URL en una ventana de incógnito (Chrome) o privada (Firefox/Safari). Esto evita todas las cookies en caché, extensiones y credenciales almacenadas.

Si la página funciona en modo incógnito pero no en tu navegador normal, el problema es una cookie en caché o una extensión del navegador que interfiere con la autenticación. Desactiva las extensiones una por una para encontrar la causante.

4. Verifica la URL

Asegúrate de visitar la URL correcta. Algunos servidores devuelven 401 en rutas que exigen autenticación, aunque la ruta en sí sea errónea. Quizá estés intentando entrar en una zona restringida que no era para ti.

Comprueba si existe una versión pública de la página en otra URL. Por ejemplo, example.com/admin/ puede devolver 401 mientras que example.com/ es de acceso público.

¿No estás seguro de que el sitio funcione? Prueba Verificador de páginas caídas: lo abre desde 11 lugares, así que distingues un problema de inicio de sesión de una caída.

Cómo solucionar el error 401 como desarrollador

Para desarrolladores que trabajan con APIs, los errores 401 generalmente están relacionados con el header Authorization, el formato del token o el ciclo de vida de las credenciales. Estas son las soluciones más comunes.

5. Verifica el Header Authorization

El error más común de los desarrolladores es un header Authorization mal formado. Cuando el servidor envía un header WWW-Authenticate, indica el esquema que espera; muchas API JSON (como las de GitHub y OpenRouter) lo omiten y explican el problema en el cuerpo de la respuesta.

Comprueba que tu header coincide con el formato requerido. Los esquemas más habituales son Bearer (para tokens) y Basic (para usuario:contraseña codificado en Base64).

# Bearer token authentication (most APIs)
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." https://api.example.com/data

# Basic authentication (username:password in Base64)
curl -u "username:password" https://api.example.com/data
# Equivalent to:
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" https://api.example.com/data

# Common mistakes that cause 401:
# Missing "Bearer " prefix:  Authorization: eyJhbGci...  ← WRONG
# Extra space:               Authorization: Bearer  eyJ... ← many servers reject it
# Wrong scheme:              Authorization: Basic eyJhbGci... ← WRONG

Después lee el header WWW-Authenticate de la respuesta 401: indica el esquema que espera el servidor. El verificador de encabezados HTTP de DNS Robot muestra la respuesta completa.

6. Comprueba la validez de la clave de API

Las claves de API dejan de funcionar cuando se rotan o se revocan, cuando la cuenta se suspende o se pasa a un plan inferior, o cuando se usa una clave de prueba contra producción. (Un límite de tasa responde 429, y una clave sin acceso a un endpoint suele recibir 403.)

Comprueba en el panel del proveedor que la clave sigue activa y pruébala directamente:

# Test a key: print only the status code (a real GET; some APIs reject HEAD)
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/me
# 200 = the key works
# 401 = the key is missing, wrong, revoked or expired
# 403 = the key works but isn't allowed to use this endpoint

# Common slips:
# 1. A space or newline after the key in .env:   API_KEY="abc123 "
# 2. The test key in production, or the reverse
# 3. An empty variable, so the header is just "Authorization: Bearer"

7. Gestiona la expiración y renovación de tokens

Los tokens JWT y los tokens de acceso OAuth tienen una vida limitada, normalmente de 15 minutos a 24 horas. Cuando expiran, todas las llamadas a la API devuelven 401 hasta que obtienes un token nuevo.

Si tienes un token de actualización (OAuth 2.0 y la mayoría de configuraciones JWT), cámbialo por un nuevo token de acceso; si no, inicia sesión de nuevo.

# Read a JWT's payload (tokens use base64url, so plain base64 -d often fails)
python3 -c 'import sys,base64,json; p=sys.argv[1].split(".")[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p+"==")),indent=2))' "$TOKEN"
# "exp" is a Unix timestamp; compare it with: date +%s

# OAuth 2.0: get a new access token with the refresh token
curl -X POST https://auth.example.com/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

8. Soluciona problemas de CORS Preflight

Cuando una página web llama a una API de otro dominio con un header Authorization, el navegador envía antes una solicitud preflight OPTIONS, y el preflight nunca lleva credenciales. Si el servidor exige autenticación en OPTIONS, responde 401, el preflight falla y el navegador muestra un error de CORS: la solicitud real nunca se envía.

La solución: deja pasar las solicitudes OPTIONS sin autenticación en los endpoints con CORS.

# Nginx — allow OPTIONS requests without auth
location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin https://app.example.com;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
        add_header Access-Control-Allow-Headers "Authorization, Content-Type";
        add_header Access-Control-Max-Age 86400;
        return 204;
    }

    # CORS header on every other answer, the 401 included, or the browser reports a CORS error
    add_header Access-Control-Allow-Origin https://app.example.com always;

    # Normal auth for other methods
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Cómo solucionar el error 401 como administrador del sitio

Si tus visitantes o usuarios están reportando errores 401, el problema está en la configuración de autenticación de tu servidor. Sigue estas verificaciones.

9. Revisa la configuración de autenticación del servidor

Comprueba que la autenticación solo esté activada en las rutas que la necesitan. Un error habitual es proteger todo un directorio o sitio cuando solo algunas rutas deberían exigir inicio de sesión.

En nginx, revisa tus directivas auth_basic; en Apache, AuthType y Require. En Node.js/Express, revisa el orden de los middleware: un app.use(auth) registrado antes de tus rutas públicas las protege también, así que registra primero las rutas públicas o aplica la autenticación solo al router protegido.

# Nginx — WRONG: protects everything, including public pages
server {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    # All pages now require login — including your homepage!
}

# Nginx — CORRECT: only protect admin routes
server {
    location / {
        # Public — no auth required
    }
    location /admin/ {
        auth_basic "Admin Area";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

10. Revisa las reglas de autenticación del .htaccess

En Apache, los archivos .htaccess pueden activar la autenticación Basic o Digest en un directorio. Si un directorio público tiene un .htaccess con directivas AuthType y Require, todos los visitantes reciben un 401 con solicitud de inicio de sesión.

Busca archivos .htaccess en el directorio afectado y en todos los directorios superiores: Apache aplica las reglas de todos los .htaccess de la ruta.

# Find all .htaccess files with auth rules
find /var/www/html -name '.htaccess' -exec grep -l 'AuthType\|AuthUserFile\|Require valid-user' {} \;

# Example .htaccess that causes 401 for everyone:
# AuthType Basic
# AuthName "Restricted Area"
# AuthUserFile /etc/apache2/.htpasswd
# Require valid-user

# Fix: remove auth lines from public directories,
# or move them to the specific /admin/.htaccess only

11. Asegúrate de que el Header Authorization llegue a tu aplicación

El cliente envía credenciales correctas, pero la aplicación nunca las ve. Dónde se pierde el header:

nginx reenvía Authorization al backend por defecto, así que no necesitas líneas adicionales; pero si la misma ubicación usa auth_basic, el login de nginx se apropia del header (consulta la sección de nginx más arriba). Apache oculta Authorization a PHP-FPM y a los scripts CGI salvo que actives CGIPassAuth (Apache 2.4.13+), la causa clásica de 401 en las API de WordPress y Laravel detrás de Apache.

# Apache 2.4.13+ (inside a <Directory> block, or .htaccess): pass Authorization to PHP-FPM and CGI
CGIPassAuth On

# Older Apache: copy it into an environment variable instead
SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1

Depuración de errores 401 con HTTP Headers

La forma más rápida de diagnosticar un 401 es leer la respuesta: el header WWW-Authenticate, cuando el servidor lo envía, indica qué inicio de sesión quiere, y las API JSON suelen explicar el error en el cuerpo.

Usa el verificador de encabezados HTTP de DNS Robot (si el 401 solo aparece tras una redirección, el verificador de redirecciones muestra qué salto lo devuelve) o curl desde una terminal:

# Print the response headers of a real GET
curl -sS -D - -o /dev/null https://api.example.com/protected-endpoint

# A 401 often carries one of:
# WWW-Authenticate: Bearer realm="api", error="invalid_token"
# WWW-Authenticate: Basic realm="Admin Area"

# It tells you:
# - the scheme (Bearer, Basic, Digest, Negotiate)
# - the realm (which area is protected)
# - for Bearer tokens, the error: invalid_request, invalid_token or insufficient_scope

Si WWW-Authenticate dice Bearer, necesitas un token; si dice Basic, un usuario y una contraseña. error="invalid_token" significa que el token está expirado, revocado, mal formado o no es válido por otro motivo. ¿Ningún header? Lee el cuerpo de la respuesta: muchas API ponen allí el motivo.

¿El error 401 afecta el SEO?

Un 401 en una página pública la saca de Google. Google trata todos los códigos 4xx salvo el 429 de la misma forma: el rastreador informa de que el contenido no existe y una URL indexada se elimina (documentación de Google sobre el rastreo).

Los 401 en páginas que deben exigir inicio de sesión (paneles de administración, dashboards, API) son normales: Google no penaliza a un sitio por ellos. Pero no uses 401 ni 403 para frenar a Googlebot; según Google, no afectan a la frecuencia de rastreo.

El problema es un 401 en páginas que deberían ser públicas, normalmente por una autenticación aplicada a todo el sitio, o por una regla de CDN o proxy que pide credenciales en rutas públicas.

Cómo prevenir errores 401

La prevención te ahorra depuración después. Sigue estas prácticas para minimizar errores 401 en tus aplicaciones y sitios web.

• Implementa la renovación automática de tokens — usa tokens de actualización para obtener tokens de acceso nuevos de forma silenciosa antes de que expiren
• Define bien los ámbitos de autenticación — protege solo las rutas que de verdad lo necesitan y mantén abiertas las páginas públicas
• Usa mensajes de error claros — devuelve cuerpos JSON útiles junto al 401, no solo el código de estado
• Supervisa los fallos de autenticación — configura alertas para los picos de respuestas 401, que pueden indicar problemas de credenciales o ataques
• Sincroniza los relojes de los servidores — usa NTP para mantener todos los servidores a pocos segundos de UTC y evitar rechazos de JWT por desfase de reloj
• Prueba con el verificador de encabezados HTTP — comprueba con regularidad que las páginas públicas devuelven 200 y las protegidas devuelven 401, como se espera
• Documenta tu esquema de autenticación — deja claro en la documentación de tu API el formato esperado del header Authorization
• Gestiona el CORS preflight — permite siempre las solicitudes OPTIONS sin autenticación en los endpoints de la API