Error guide

401 Unauthorized

The request needs authentication and did not supply valid credentials — the server does not know who you are.

A 401 means the request requires authentication and did not arrive with credentials the server accepted. Either nothing was sent, or what was sent was invalid, expired, or in a form the server does not recognise. A correct 401 also includes a WWW-Authenticate header saying which scheme to use.

The distinction from 403 is about identity versus permission, and it is worth insisting on because it changes what you do next. A 401 says the server does not know who you are — authenticate and retry. A 403 says the server knows exactly who you are and the answer is still no — retrying with the same identity will not help.

The name is a historical misnomer worth knowing about, because it sends people looking in the wrong place. Despite reading Unauthorized, a 401 is about authentication — proving who you are — while 403 Forbidden is the code about authorisation, which is what you are permitted to do once that is settled. The specification has acknowledged the confusion and kept the name for compatibility.

Common causes

  • An expired access token, session or signed cookie.
  • A rotated API key that the client is still sending in its old form.
  • The Authorization header being stripped by a proxy, a redirect, or a CDN configured not to forward it.
  • A clock skew large enough to make a time-limited token invalid on arrival.
  • The wrong scheme entirely — Basic where Bearer is expected, or a raw token with no scheme prefix.
  • A correct token aimed at the wrong environment, tenant or audience.

How to diagnose it

  1. Read the WWW-Authenticate header on the response: it names the scheme, and often the specific reason.
  2. Decode the token, if it is a JWT, and check its expiry, issuer and audience before assuming it is malformed.
  3. Confirm the Authorization header actually arrives — log it, redacted, at the first hop that sees it.
  4. Check whether the failing requests are the ones that followed a redirect: most clients drop auth headers across a redirect to another host.
  5. Compare the server's clock with a reliable source if tokens are failing intermittently and inexplicably.

Whose fault is it? Usually the client's side

The request is at fault by definition, but the underlying cause is frequently on the server side: a rotation nobody told the client about, a proxy that stopped forwarding the header, or an auth service that is itself failing and rejecting valid credentials.

What monitoring sees

A monitor getting a 401 usually needs its credentials updated rather than indicating an outage, which is why credential expiry is one of the most common causes of a false page. Uptimely lets a monitor send its own headers, so an authenticated endpoint can be checked properly instead of being pointed at an unauthenticated stand-in that stays green while the real one fails.

Related error guides

Terms used on this page

Questions

What is the difference between 401 and 403?

401 means the server does not know who you are — authenticate and try again. 403 means it knows and is refusing anyway. If retrying with valid credentials could succeed, it is a 401; if it could not, it is a 403.

Why does my API monitor return 401 intermittently?

Usually a token expiring mid-run, a rotation that reached some instances before others, or clock skew invalidating a time-limited token. Intermittent auth failures are much more often about time than about the credential itself.

One of the Uptimely HTTP and network error guides, written for the person who operates the server rather than the one refreshing the page. Something here read wrong to you? Email support@getuptimely.com.