401 Unauthorized
The request lacks valid credentials. Despite the name, this is about authentication (who you are), not authorisation (what you may do).
At a glance
- Status code
- 401 Unauthorized
- Class
- 4xx, client error, the request itself is the problem
- Defined in
- RFC 9110
- Cacheable by default
- no
- Response body
- Optional, plus a mandatory WWW-Authenticate header.
In detail
The server does not know who is asking, or the credentials it was given are expired or wrong. Retrying with better credentials may work, which is the whole difference from 403.
The specification requires a WWW-Authenticate header naming the scheme. Most APIs omit it, which is technically a violation and also removes the one machine-readable hint the client had.
If a token that worked five minutes ago now returns 401, check clock skew and token lifetime before suspecting revocation. An expired exp claim is by far the most common cause.
Examples
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"
Content-Type: application/json
{"error":"token expired"}Things that catch people out
- 401 and 403 are frequently swapped. If sending different credentials could succeed, it is 401. If no credentials would ever succeed for this action, it is 403.
- A browser shown a 401 with a Basic WWW-Authenticate header pops a native login dialog, which is almost never what a single-page application wants.
Try it: HTTP Request Builder
Build a request with any method, headers and body, send it, and read the status line the server returns.
HTTP Request Builder
LOCAL · Browser-OnlyBuild and test HTTP requests with custom headers and body
Authentication
Headers
Generate Code
curl -X GET 'https://api.example.com/endpoint' \
-H 'Content-Type: application/json'Showing a sample URL. Enter your endpoint above to update the snippet.
Related HTTP status codes
All http status codes →403 Forbidden
The server understood the request and refuses to fulfil it. Unlike 401, sending different credentials will not help.
407 Proxy Authentication Required
A proxy between the client and the server needs credentials. This is 401 raised by the intermediary rather than by the origin.
400 Bad Request
The server refused the request because it was malformed. The client must change something before retrying, because repeating the same bytes will fail.
402 Payment Required
Reserved for future use in the original specification, and now used in practice by APIs to signal that a plan limit or unpaid invoice is blocking the request.
404 Not Found
The server has no representation for this URL and will not say whether it ever did. The most common status code on the web after 200.
405 Method Not Allowed
The URL exists but does not support the method you used. The Allow header lists the methods it does support.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL