What is 401 Unauthorized?
Definition
401 Unauthorized is the HTTP status code meaning a request was not applied because it lacks valid authentication credentials for the target resource. Despite the name, it is about authentication rather than authorization. The server must send a WWW-Authenticate header describing how to authenticate, and the client may retry with new or corrected credentials.
Also known as: HTTP 401, 401 error, authentication required
A misleading name
This is one of HTTP's best-known naming accidents. A 401 is called "Unauthorized", but what it describes is missing or failed authentication: the server doesn't know who you are. When the server does know who you are and you are simply not allowed in, the right code is 403 Forbidden, which is an authorization problem.
A practical way to remember it: 401 says "identify yourself" and expects the client to try again with credentials; 403 says "I know who you are, and no".
WWW-Authenticate is mandatory
RFC 9110 requires a server that sends 401 to include a WWW-Authenticate header with at least one challenge that applies to the resource. Without it, the client has no idea what to do next.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="staging"
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token",
error_description="The access token expired"The first makes the browser show its built-in username and password prompt. The second is the form used by token-based APIs and comes from the OAuth 2.0 bearer token standard, RFC 6750.
Getting 401 versus 403 right in an API
| Situation | Code | What the client should do |
|---|---|---|
| No token sent | 401 | Authenticate and retry |
| Token expired, revoked or malformed | 401 (invalid_token) | Get a new token and retry once |
| Valid token without the required scope | 403 (insufficient_scope) | Do not retry with the same token |
The distinction drives client code. A well-behaved client refreshes its access token on a 401 and retries the request once; on a 403 it knows a refresh will not help and shows a permission error instead. An API that answers every permission failure with 401 pushes its clients into pointless refresh loops.
Search engines and 401
Google treats 401 like other 4xx codes, as content that doesn't exist: the URL isn't indexed, and if it was, it is removed. In Search Console such pages are listed as "Blocked due to unauthorized request (401)". That behaviour is useful: putting a staging environment behind HTTP authentication is far more robust than relying on robots.txt, which blocks crawling but does not by itself stop a linked URL from appearing in the index. Google also says explicitly not to use 401 or 403 to limit crawl rate.