Skip to content
4xx · client errorSent by App | Proxy | CDN

401Unauthorized

The server does not know who you are. Send valid credentials and try again.

How you get a 401

The request arrives with no credentials. The app cannot tell who is asking, so the app sends 401 with a WWW-Authenticate header. Nothing is read from the database.

Who sends itApp · Proxy · CDN

  1. Browser
  2. CDN
  3. Proxy
  4. App
  5. DB

Typically the app or an API gateway in front of it, whichever checks credentials first. A proxy sends it when it protects a site with a password by itself.

In short

What a 401 Unauthorized means

A 401 Unauthorized is badly named: it is about authentication, not permission. The server is saying it does not know who is asking, because the request carried no credentials or carried ones that are missing, expired or wrong. The fix is on the client side and is usually simple: log in, refresh the token, or send the header correctly. The response is required to include a WWW-Authenticate header describing how to authenticate. Whichever box checks credentials first sends the 401, typically the application or an API gateway in front of it. The pairing to remember is with 403. A 401 means “I don't know who you are”; a 403 means “I know who you are, and the answer is no”.

Common causes of a 401

  1. 1No Authorization header or session cookie was sent.

    How to check: The response should name the expected scheme.

    curl -sI https://api.example.com/me | grep -i www-authenticate
  2. 2The token has expired.

    How to check: Decode the token and compare its expiry time with the current time. Refresh it and retry once.

  3. 3The header is malformed: wrong scheme, a missing “Bearer”, a stray space or quote.

    How to check: Print the exact header your client sends.

    Authorization: Bearer <token>
  4. 4A redirect to another host dropped the Authorization header. Clients remove it on purpose when the host changes.

    How to check: Follow the request with redirects visible and see whether the final host differs.

    curl -sIL https://example.com/api/me | grep -iE '^HTTP|location'

Retry or not?

Retry only after fixing the request · Re-authenticate, then once

The same request with the same credentials gets the same 401. Log in or refresh the token, then retry once. If that also fails, stop: looping on 401 can lock the account.

Headers that matter

WWW-Authenticate
Required on a 401. Says which authentication scheme to use, and often why the last attempt failed.
Authorization
Request header carrying the credentials, such as a bearer token.

In the real world

RFC vs real deployments

RFC 9110 requires a 401 to carry a WWW-Authenticate challenge, and reserves 403 for credentials that are valid but not sufficient. Real APIs blur both rules. Many send 401 with no WWW-Authenticate at all. Some send 403 for a missing token, and some send 401 for a valid user who lacks permission. Others answer 404 for both, to avoid revealing that the resource exists.

Seen in a real outage

When the identity service fails, every product behind it starts refusing logins at once. In December 2020 Google's sign-in failed worldwide for 45 minutes, although the account data was intact.

Your turn

Which code is it?

An API call worked this morning. Now it returns 401 with “WWW-Authenticate: Bearer error="invalid_token"”. Nothing was deployed. What should the client do?

Often confused with

401 questions

What is the difference between 401 and 403?
A 401 means the server does not know who you are: credentials are missing or invalid. A 403 means it knows who you are and still refuses.
Who sends a 401?
Whichever box checks credentials first: typically the application or an API gateway. A proxy sends it when it password-protects a site by itself.
Why is it called Unauthorized if it is about authentication?
The name is historical. The meaning in the standard is that the request lacks valid authentication credentials. Lack of permission is 403.

Sources: RFC 9110: 401 Unauthorized (section 15.5.2) ↗ · RFC 9110: WWW-Authenticate (section 11.6.1) ↗ · Report a problem

Diagrams are our own simulations. All wording is original and paraphrases the linked sources.

Practise this in the DNS / HTTP track

Two-minute animated lessons, then boss fights from real outages. Free, no account needed.

Start the track