What 401 Unauthorized means

401 Unauthorized indicates that the request lacks valid authentication credentials. The response should include a WWW-Authenticate header describing how to authenticate. 403 Forbidden means the server understood the request and the identity, but the identity lacks permission — re-authenticating will not help.

When a server should return it

  • 401: missing token, expired token, invalid signature, or a failed login attempt on a protected resource.
  • 403: a valid user trying to access another user's data, an admin-only endpoint, or a blocked IP.
  • 404: sometimes preferable to 403 when revealing the resource's existence is itself sensitive.

Example response

http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{"title": "Forbidden", "status": 403, "detail": "role 'viewer' cannot delete projects"}

Why you might see it unexpectedly

  • A token expiring mid-session and the client not refreshing it.
  • Role checks applied to the wrong resource owner (IDOR bugs).
  • A gateway returning 401 for a request that never reached the app.
  • Returning 403 for an unauthenticated request, which tells crawlers the resource exists.

Related status codes

407 Proxy Authentication Required is for proxy credentials. 404 Not Found can intentionally hide a resource. 400 Bad Request is syntax, not identity.