401 Unauthorized
The request lacks valid authentication credentials for the target resource.
Status
HTTP/1.1 401 Unauthorized
Details
- Category: 4xx
- Status: Standard. Registered with IANA and defined by a current standards-track RFC.
- Specification: RFC 9110 §15.5.2
- Cacheable: Only with explicit cache headers
- Response body: Allowed
- Retry: Retry only after changing the request
Despite the name, 401 means unauthenticated. The server does not know who you are, or the credentials you sent were rejected. Every 401 must include a WWW-Authenticate header naming at least one authentication scheme the client can use, which is what lets a browser show a login prompt or a client pick the right token type.
The distinction from 403 is worth holding on to: 401 means try again with credentials, 403 means credentials will not help. Retrying a 401 with the same token is pointless.
Note: Despite the name, 401 means unauthenticated. Use 403 when the caller is known and simply not permitted.
Headers
- WWW-Authenticate: Required. Names the scheme and parameters, e.g. Bearer realm="api", or Basic realm="admin".
Common causes
- No Authorization header was sent.
- An expired, revoked, or malformed access token.
- A session cookie that expired or was issued for a different host.
- Clock skew large enough to invalidate a signed token or request signature.
How to fix it
As the client
- Refresh the token or re-authenticate, then replay the request.
- Check the header format. Bearer tokens need the Bearer prefix, and Basic needs base64 of user:password.
- Confirm the credential belongs to the environment you are calling. Test keys against production endpoints return 401 constantly.
- Verify system time. Signature-based auth fails when the clock drifts by more than the allowed window.
As the server
- Always send WWW-Authenticate. A 401 without it leaves clients unable to choose a scheme.
- Distinguish expired from invalid in the error body so clients know whether to refresh or re-authenticate.
- Do not use 401 for authorization failures. Use 403 when the caller is known but not permitted.
Examples
Calling an API with an expired token
A request carrying a token that has expired:
HTTP request
GET /api/v2/order HTTP/1.1 Host: api.example.com Authorization: Bearer expired_token
The response names an authentication scheme in WWW-Authenticate, which is what tells the client how to try again:
HTTP response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"
Content-Type: application/json; charset=utf-8
{"error":"invalid_token","detail":"Token expired at 2026-08-01T00:00:00Z"}
Notes for proxy users
401 comes from the destination site, not from the proxy. The proxy equivalent is 407 Proxy Authentication Required. If you are debugging credentials and see both, fix the 407 first: the request never reached the site.