401 vs 403, and when to use each

The difference between 401 and 403 is a common source of bugs — not because the spec is unclear, but because it’s easy to conflate identity with permission.

The distinction

A 401 Unauthorized means the server doesn’t know who you are. The correct fix is to authenticate: provide a token, log in, or attach credentials. The WWW-Authenticate header tells the client how.

A 403 Forbidden means the server knows exactly who you are — and you’re not allowed. No amount of re-authentication changes this outcome.

teksSalin
GET /admin/settings
→ 401  if no Authorization header (who are you?)
→ 403  if token is valid but role is "viewer" (you can't do this)

There is one common exception: APIs sometimes return 404 instead of 403 to avoid leaking the existence of a resource to unauthorized callers. That’s a deliberate security tradeoff, not a bug.