HTTP 401 Unauthorized – What It Means and How to Fix It

Learn what HTTP 401 means, why it is about authentication rather than permission, how WWW-Authenticate works, and the causes worth checking first.

A 401 means the request lacked valid authentication credentials. Despite its name, it is about identity rather than permission — that distinction is what separates it from 403.

1. What HTTP 401 Means

The server could not authenticate the request.

• No credential, or an unacceptable one.
• The response should include a challenge naming the scheme, in WWW-Authenticate.
• Retrying with valid credentials is expected to succeed.

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

2. HTTP 401 Versus 403

If supplying a valid credential would change the outcome, 401 is correct. If the caller is known and simply not permitted, 403 is.

3. Common Causes

• Missing header. The credential was never attached, often after a refactor moved the request.
• Wrong header name. Services that expect a custom key header ignore Authorization entirely, and vice versa.
• Expired token. Access tokens are short-lived by design; the refresh path failed silently.
• Wrong environment. A staging key used against production, or the reverse.
• Malformed value. A missing Bearer prefix, stray whitespace, or a truncated copy-paste.
• Clock skew. Signed tokens fail validation when the client's clock is materially wrong.
• Rotated credential deployed to some workers and not others.

4. Diagnosing It

Read the challenge header first — well-built APIs put a reason in it, such as an expired or malformed token.

curl -i -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/me

Then check the credential's shape without printing it: its length, whether it has the expected structure, and whether the same value works against a known-good endpoint.

5. How to Fix It

• Confirm the exact header name the API documents.
• Refresh the token and verify the refresh flow actually runs before expiry.
• Check environment configuration — the wrong key is more common than an invalid one.
• Verify the system clock where signed tokens are used.
• Ensure every worker or container received the rotated credential.

6. Secret Handling While Debugging

Never print the credential. Log its presence, length, and prefix shape only, and redact Authorization headers before any request dump reaches logs or issue trackers.

A leaked token in a bug report is a real incident, and it happens most often during exactly this kind of debugging.

7. Real-World Examples

• A background job whose token expired and whose refresh silently failed.
• A client sending Authorization to an API that expects a custom key header.
• A deployment where one replica kept the old secret after rotation.
• A device with a wrong clock rejecting freshly issued signed tokens.

8. Summary

HTTP 401 means authentication failed or was absent, and the WWW-Authenticate header usually names the reason. It differs from 403 in that a valid credential would change the outcome.

Check the header name, expiry, environment, and rotation state — and redact credentials while doing so.

Potential Related Glossary

• Axios
• Parsing
• Data Structure
• Web Crawling