Status codes · one code401Unauthorized

What a 401 Unauthorized response means, who is at fault, what a visitor should do and what the server owner should do.

Open the reference on this code
What is happening

The server does not know who you are

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Restricted"

Credentials were not sent or no longer work. In a browser this is the login prompt; in an API it is a refusal carrying the WWW-Authenticate header, which states how to authenticate. Most often a 401 means an expired token rather than missing rights: it was issued for an hour and the request arrived a day later.

Code
Who is at faultClient error
Class4xx Client error
Headers
WWW-Authenticatewhich authentication scheme is expected
01

What to do

If it is someone else's site

Sign in again — that is enough in the vast majority of cases: the session expired. If signing in does not help and you are sure the access should be there, the problem is no longer a 401: the server would recognise you and answer 403.

If it is your server

A 401 must carry WWW-Authenticate — without it the client does not know what to present, and standard libraries will not retry. Keep two cases apart: not authenticated is 401, authenticated but not allowed is 403. The common mistake runs the other way: an expired token is answered with 403, and the client never tries to refresh it, because retrying a 403 is pointless.

02

Easily confused with

403Forbidden

the server recognised you but forbids the action. Signing in again will not help: this is about rights.

403
407Proxy Authentication Required

the same, but it is the proxy demanding authentication rather than the site.

407
404Not Found

a protected resource is sometimes returned as 404 on purpose — so as not to confirm that it exists.

404
03

How to check

curl -i https://api.example.com/me | head -5

see whether WWW-Authenticate arrives and which scheme is required

curl -H "Authorization: Bearer $TOKEN" -i https://api.example.com/me | head -1

check one specific token instead of guessing from the interface

Find another code

The reference holds sixty-four codes searchable by number, name and meaning — plus a breakdown of confusing pairs such as 401 and 403.

Open the reference on this codeAll codes

Updated

«» added to favorites