Tech

Explainer

Updated

What does the HTTP 401 status code mean?

Key facts

A server that sends a 401 must also send a WWW-Authenticate header with at least one challenge, under RFC 9110.

The HTTP 401 status code means the server did not apply a request because the request lacks valid authentication credentials for the resource it asked for, according to RFC 9110, Section 15.5.2, the IETF document titled HTTP Semantics. In the words of the standard, "The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource."

When a server sends a 401

Section 11.4 of RFC 9110 says an origin server should send a 401 when a request for a protected resource omits credentials, contains invalid credentials such as a bad password, or contains only partial credentials, as happens when an authentication scheme needs more than one round trip. A 401 belongs to the 4xx class, which RFC 9110, Section 15.5 describes as the class of status codes indicating that the client seems to have erred.

What a 401 response must include

A server that generates a 401 response must send a WWW-Authenticate header field containing at least one challenge that applies to the target resource, under RFC 9110, Section 15.5.2. Section 11.3 explains that an origin server uses a 401 response to challenge the authorization of a user agent. A user agent then authenticates by sending an Authorization header field with its credentials, as described in Section 11.6.2.

What a 401 means when credentials were already sent

If the request already included authentication credentials, the 401 response means authorization has been refused for those credentials, according to RFC 9110, Section 15.5.2. The user agent may repeat the request with a new or replaced Authorization header field. When the new 401 carries the same challenge as the last one and the user agent has already tried to authenticate at least once, the standard says the user agent should show the user the content of the response, because it usually contains diagnostic information.

How 401 differs from 403 and 407

A 403 (Forbidden) means the server understood the request but refuses to fulfill it, and if credentials were sent, the server considers them insufficient to grant access, under RFC 9110, Section 15.5.4. Section 11.4 says a server that receives valid credentials that are not adequate to gain access ought to respond with 403. A 407 (Proxy Authentication Required) is similar to 401, but Section 15.5.8 says it means the client must authenticate itself to use a proxy, and the proxy must send a Proxy-Authenticate header field.

CodeNameMeaning under RFC 9110
401UnauthorizedValid authentication credentials are missing
403ForbiddenThe request is understood but refused
407Proxy Authentication RequiredThe client must authenticate to a proxy

Where the 401 code is defined

RFC 9110, titled HTTP Semantics, was published in June 2022 as a product of the Internet Engineering Task Force and an Internet Standards Track document, numbered STD 97, and it obsoletes earlier specifications including RFC 7231 and RFC 7235. The IANA HTTP Status Code Registry, maintained by IANA, records 401 with the description Unauthorized and cites RFC 9110, Section 15.5.2, as its reference.

Have another question?