Error HTTP 401 Unauthorized: Qué Significa y Cómo Solucionarlo

¿Qué Es un Error 401 Unauthorized?

Un error 401 Unauthorized es un código de estado HTTP que significa que el servidor requiere autenticación para el recurso solicitado, pero la solicitud no incluyó credenciales o las credenciales proporcionadas eran inválidas.

La especificación HTTP (RFC 9110, Sección 15.5.2) lo define como: la solicitud carece de credenciales de autenticación válidas para el recurso de destino. El servidor que genera la respuesta 401 debe incluir un header WWW-Authenticate indicando qué esquema de autenticación utilizar.

En términos simples: el servidor está preguntando "¿quién eres?" antes de permitir el acceso. O no proporcionaste ninguna identificación, o la identificación que proporcionaste era incorrecta.

Cómo Se Ve un Error 401

El error 401 aparece de diferentes formas dependiendo del servidor, navegador y aplicación. Estos son los mensajes más comunes que encontrarás.

• 401 Unauthorized — el mensaje de respuesta HTTP estándar

• HTTP Error 401 – Unauthorized — común en aplicaciones IIS y ASP.NET

• 401 Authorization Required — página de error predeterminada de Nginx

• Error 401 — forma abreviada en las barras de dirección del navegador

• Access Denied: Invalid credentials — páginas de error personalizadas de aplicaciones

• Authentication Required — ventana emergente del navegador para autenticación Basic/Digest

• Invalid API Key — común en respuestas de APIs REST

• Token Expired — el token JWT u OAuth necesita renovación

Cuando un servidor envía un 401, la mayoría de los navegadores muestran una ventana emergente de inicio de sesión pidiendo nombre de usuario y contraseña. Si el servidor usa autenticación basada en tokens (como APIs), verás el error en el cuerpo de la respuesta JSON.

401 vs 403: ¿Cuál Es la Diferencia?

Los códigos de estado 401 y 403 se confunden frecuentemente, incluso por desarrolladores experimentados. La distinción es simple: 401 significa "no sé quién eres" mientras que 403 significa "sé quién eres, pero no tienes permiso."

Una regla práctica: si proporcionar el nombre de usuario y contraseña correctos (o clave de API) solucionaría el problema, 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

Entender por qué ocurre un error 401 depende de si eres un usuario regular, un desarrollador que llama a una API o un administrador de servidor. Estas son las causas más frecuentes.

• Nombre de usuario o contraseña incorrectos — la causa más básica, especialmente después de un restablecimiento de contraseña

• Token de autenticación expirado — los tokens JWT, tokens de acceso OAuth y cookies de sesión tienen tiempos de expiración

• Header Authorization ausente — la solicitud no incluyó ninguna credencial

• Clave de API inválida — la clave fue revocada, rotada o copiada incorrectamente

• Esquema de autenticación incorrecto — el servidor espera Bearer token pero recibió Basic auth, o viceversa

• Desfase de reloj (clock skew) — la validación JWT falla cuando los relojes del servidor y del cliente están desincronizados por más de unos minutos

• CORS preflight eliminando headers — el navegador elimina el header Authorization de las solicitudes preflight OPTIONS

• Caché del navegador desactualizada — el navegador envía una cookie de sesión en caché expirada en lugar de solicitar una nueva

• Configuración incorrecta del proxy inverso — Nginx o Apache elimina el header Authorization antes de reenviarlo al backend

• Credenciales con límite de tasa o revocadas — demasiados intentos fallidos activaron el bloqueo de la cuenta

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

Tu navegador puede estar enviando una cookie de sesión expirada o un token de autenticación en caché. Limpiar estos datos obliga al navegador a solicitar nuevas credenciales al servidor.

Chrome:  Settings → Privacy → Clear browsing data → Cookies + Cached images
Firefox: Settings → Privacy → Clear Data → Cookies + Cache
Safari:  Settings → Privacy → Manage Website Data → Remove All
Edge:    Settings → Privacy → Clear browsing data → Cookies + Cache

Después de limpiar, cierra el navegador completamente (no solo la pestaña), vuelve a abrirlo y navega a la página de nuevo. Deberías ver un nuevo formulario de inicio de sesión.

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 que estás visitando la URL correcta. Algunos servidores devuelven 401 para rutas que requieren autenticación, incluso si la ruta en sí es incorrecta. Podrías estar intentando acceder a un área restringida que no deberías visitar.

Verifica si existe una versión pública de la página en una URL diferente. Por ejemplo, example.com/admin/ podría devolver 401 mientras que example.com/ es accesible públicamente.

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. El header WWW-Authenticate en la respuesta del servidor te indica exactamente qué esquema espera.

Verifica que tu header coincida con el formato requerido. Los esquemas más comunes son Bearer (para tokens) y Basic (para usuario:contraseña codificados 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... ← WRONG
# Wrong scheme:              Authorization: Basic eyJhbGci... ← WRONG

Siempre verifica el header WWW-Authenticate en la respuesta 401. Te indica exactamente qué espera el servidor. Usa la herramienta HTTP Headers de DNS Robot para inspeccionar la respuesta completa.

6. Comprueba la Validez de la Clave de API

Las claves de API pueden dejar de funcionar silenciosamente por varias razones: la clave fue rotada, la cuenta asociada fue degradada, la clave alcanzó su límite de tasa, o fue configurada para endpoints diferentes a los que estás llamando.

Verifica que tu clave siga activa en el panel del proveedor. Muchas APIs (Google, AWS, Stripe) te permiten probar la clave directamente desde su consola.

# Test if your API key is valid
curl -I -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/me
# 200 = key is valid
# 401 = key is invalid or expired
# 403 = key is valid but lacks permission for this endpoint

# Check common API key issues:
# 1. Trailing whitespace in .env file:  API_KEY="abc123 " ← trailing space
# 2. Wrong environment:                 using test key on production
# 3. Missing prefix:                    some APIs need "sk_live_" prefix

7. Gestiona la Expiración y Renovación de Tokens

Los tokens JWT y los tokens de acceso OAuth tienen un tiempo de vida limitado — generalmente de 15 minutos a 24 horas. Cuando expiran, cada llamada a la API devuelve 401 hasta que obtengas un token nuevo.

La solución depende de tu flujo de autenticación. OAuth 2.0 usa un refresh token para obtener un nuevo token de acceso sin reautenticación. Los sistemas basados en JWT generalmente requieren un nuevo inicio de sesión.

# Decode a JWT token to check its expiry (works on macOS and Linux)
echo "eyJhbGciOiJIUzI1NiIs..." | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool
# Look for "exp" field — it's a Unix timestamp
# Compare with current time: date +%s

# OAuth 2.0 refresh token flow
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 un navegador envía una solicitud cross-origin con un header Authorization, primero envía una solicitud preflight OPTIONS. El navegador elimina automáticamente el header Authorization de esta solicitud preflight. Si tu servidor requiere autenticación en la solicitud OPTIONS, devuelve 401 antes de que la solicitud real se envíe.

La solución: configura tu servidor para permitir solicitudes OPTIONS sin autenticación en los endpoints habilitados para CORS.

# Nginx — allow OPTIONS requests without auth
location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin *;
        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;
    }

    # 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

Verifica que la autenticación esté habilitada solo en las rutas que la necesitan. Un error común es proteger un directorio o sitio completo cuando solo rutas específicas deberían requerir inicio de sesión.

En Nginx, revisa tus directivas auth_basic. En Apache, revisa las directivas AuthType y Require. En Node.js/Express, revisa el orden de tus middlewares — un middleware de autenticación colocado antes de los manejadores de rutas bloqueará todo.

# 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 servidores Apache, los archivos .htaccess pueden habilitar autenticación Basic o Digest para directorios específicos. Si un archivo .htaccess existe en un directorio público con directivas AuthType, todos los visitantes recibirán una solicitud de inicio de sesión 401.

Revisa si existen archivos .htaccess en el directorio afectado y en todos los directorios padre — Apache aplica reglas de todos los archivos .htaccess en 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. Soluciona la Eliminación de Headers por el Proxy Inverso

Si tu aplicación está detrás de Nginx, Apache o un balanceador de carga, el proxy puede eliminar el header Authorization antes de reenviar la solicitud a tu backend. Esta es una de las causas más frustrantes de errores 401 porque el cliente envía credenciales correctas pero el servidor nunca las recibe.

Revisa la configuración de tu proxy para asegurarte de que pase el header Authorization.

# Nginx reverse proxy — pass Authorization header to backend
location /api/ {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Authorization $http_authorization;  # ← Critical!
    proxy_pass_header Authorization;                      # ← Also add this
}

# Apache reverse proxy
<Location /api/>
    ProxyPass http://localhost:3000/api/
    ProxyPassReverse http://localhost:3000/api/
    RequestHeader set Authorization "expr=%{HTTP:Authorization}"  # Pass auth header
</Location>

Depuración de Errores 401 con HTTP Headers

La forma más rápida de diagnosticar un error 401 es inspeccionar los headers de la respuesta. El header WWW-Authenticate en la respuesta del servidor te indica exactamente qué método de autenticación se requiere.

Usa la herramienta HTTP Headers de DNS Robot o curl desde la terminal para ver la respuesta completa.

# Check the WWW-Authenticate header in the 401 response
curl -I https://api.example.com/protected-endpoint

# Typical 401 response headers:
# HTTP/1.1 401 Unauthorized
# WWW-Authenticate: Bearer realm="api", error="invalid_token"
# WWW-Authenticate: Basic realm="Admin Area"
# Content-Type: application/json

# The WWW-Authenticate header tells you:
# - The auth scheme (Bearer, Basic, Digest)
# - The realm (which area is protected)
# - The error reason (invalid_token, expired, etc.)

Presta especial atención al header WWW-Authenticate. Si dice Bearer, necesitas un token. Si dice Basic, necesitas un nombre de usuario y contraseña. Si incluye error=invalid_token, tu token existe pero está mal formado o expirado. Este único header generalmente te indica exactamente cuál es el problema.

¿El Error 401 Afecta el SEO?

Un error 401 en páginas públicas perjudicará tu SEO. Cuando Googlebot encuentra un 401, no puede rastrear la página y eventualmente la eliminará del índice.

Sin embargo, los errores 401 en páginas que deberían requerir autenticación (paneles de administración, paneles de usuario, endpoints de API) son completamente normales. Google espera que estas páginas estén protegidas y no penalizará tu sitio por ello.

El problema surge cuando los errores 401 aparecen en páginas que deberían ser accesibles públicamente. Esto ocurre generalmente cuando el middleware de autenticación está mal configurado o cuando un CDN/proxy inverso requiere credenciales incorrectamente 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 refresh tokens para obtener nuevos tokens de acceso silenciosamente antes de que expiren

• Define alcances de autenticación adecuados — protege solo las rutas que genuinamente necesitan autenticación, mantén las páginas públicas abiertas

• Usa mensajes de error claros — devuelve cuerpos de error JSON útiles junto con el 401, no solo el código de estado

• Monitoriza fallos de autenticación — configura alertas para picos en respuestas 401, que pueden indicar problemas de credenciales o ataques

• Sincroniza los relojes de los servidores — usa NTP para mantener todos los servidores dentro de pocos segundos del UTC, previniendo rechazos JWT por desfase de reloj

• Prueba con la [herramienta HTTP Headers](/http-headers) — verifica regularmente que las páginas públicas devuelvan 200 y las páginas protegidas devuelvan 401 como se espera

• Documenta tu esquema de autenticación — deja claro el formato esperado del header Authorization en la documentación de tu API

• Gestiona el CORS preflight — siempre permite solicitudes OPTIONS sin autenticación en los endpoints de API