HTTP 401 Unauthorized

What It Means

The HTTP 401 Unauthorized status code indicates that the request lacks valid authentication credentials. The client must authenticate to get the requested response. Despite the name "Unauthorized," this is about authentication, not authorization.

401 vs 403: The Key Difference

Common Causes

• Missing Authorization header: No token/credentials sent
• Expired token: JWT or session token has expired
• Invalid credentials: Wrong API key or password
• Malformed token: Token format is incorrect
• Revoked token: User logged out or token blacklisted

WWW-Authenticate Header

The 401 response must include a WWW-Authenticate header indicating how to authenticate:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

Common Authentication Schemes

How to Debug

# Check if token is being sent
curl -v https://api.example.com/users \
  -H "Authorization: Bearer your-token-here"

# Decode JWT to check expiration
echo "eyJhbGciOiJIUzI1..." | cut -d'.' -f2 | base64 -d

# Test with fresh token
curl -X POST https://api.example.com/auth/login \
  -d '{"email": "[email protected]", "password": "..."}' \
  -H "Content-Type: application/json"

Client-Side Handling

async function fetchWithAuth(url) {
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${getToken()}`
    }
  });

  if (response.status === 401) {
    // Token expired - refresh or redirect to login
    await refreshToken();
    return fetchWithAuth(url); // Retry
  }

  return response;
}

Best Practices

• Always include WWW-Authenticate header in 401 responses
• Don't reveal if a user exists (use same error for invalid user/password)
• Implement token refresh for better UX
• Use 401 for missing/invalid auth, 403 for insufficient permissions