1. HTTP (Hypertext Transfer Protocol)

  1. HTTP Status Codes

  1. 401 Unauthorized
    1. Writing responses (servers)
    2. Reading responses (clients)
    3. Overview table
    4. See also

401 Unauthorized

The 401 (Unauthorized) HTTP status code indicates the user lacks permission or credentials to perform the request.

It varies from 403 (Forbidden) in that 401 implies an authorization problem that can be fixed with the correct credentials. 403, by contrast, is not related to authorization, does not respond with a WWW-Authenticate header, and implies the request is understood, but not possible.

Writing responses (servers)

Use 401 (Unauthorized) when the request requires permission, and the user has not provided credentials for the operation, or has provided credentials with insufficient access.

Authorization is tested once the resource, and method handler on the resource, is known to exist; so this status code is tested after 404 (Not Found), 410 (Gone), 403 (Forbidden), and 405 (Method Not Allowed). If this reveals too much information about the resource, consider using 404 (Not Found) instead.

If permitted by the Allow request-header, return a short response body that describes that access is denied, and how to authenticate a subsequent request.

Reading responses (clients)

401 errors can be retried with different credentials. Read the WWW-Authenticate response header to determine which credentials are necessary, and show a prompt that allows the user to provide the credentials necessary. If the user did not provide any credentials, show the response body as an error message.

Overview table

Name
401
Message
401 Unauthorized
Description
The user lacks permission/credentials to perform the request.
Specification
RFC 7235: HTTP Authentication ยง3.1. 401 Unauthorized

See also