The short answer
| Status | Means | Would other credentials help? | Must include |
|---|---|---|---|
| 401 Unauthorized | "Who are you?" No valid credentials came with the request | Yes - send valid ones | A WWW-Authenticate header |
| 403 Forbidden | "I know who you are, and no." The request is understood and refused | Not the ones sent | Nothing required |
| 404 Not Found | "There is nothing here" - or nothing the server is willing to admit to | No | Nothing required |
Check authentication first and answer 401 if it fails. Then, for a caller you have identified, answer 403 if they may not have the resource, or 404 if they should not even learn that it exists. Answer 404 when it really does not exist.
401: missing or invalid credentials
The name is a historical accident. 401 is about authentication - the server does not know who is calling - not authorisation. It is the right answer when the Authorization header is missing, the token has expired, its signature does not verify, or the API key is unknown.
RFC 9110 requires a 401 response to carry a WWW-Authenticate header naming at least one way to authenticate. With OAuth bearer tokens, RFC 6750 adds an error code saying what was wrong:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired"Many APIs skip the header. Clients cope, but it is the part that tells a client library whether refreshing its token is worth trying. One caution for APIs called from a browser: a WWW-Authenticate: Basic challenge makes the browser show its own username and password dialog, so do not send that scheme unless you want the dialog.
When you are on the receiving end of a 401 with a JWT, paste the token into the JWT decoder: an exp claim in the past, a different aud than the API expects, or a token from the wrong issuer explains most of them.
403: known, but not allowed
A 403 says the server understood the request and refuses it. RFC 9110 adds that if credentials were sent, the server considers them insufficient, and the client should not simply repeat the request with the same ones. Logging in again will not help; a different account or more permissions might.
- A logged-in user who is not an admin calls an admin endpoint.
- A token is valid but lacks the scope the endpoint needs. RFC 6750 names this
insufficient_scopeand says to answer 403. - A user tries to change a resource they can read but not write.
- The refusal has nothing to do with who is calling: a blocked IP range, a failed CSRF check, a request from a country the service does not serve.
A 403 body should say enough for a legitimate caller to fix the problem, such as which permission or scope is missing. RFC 9457 defines a standard JSON shape, application/problem+json, for that:
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"type": "https://example.com/problems/missing-scope",
"title": "Missing scope",
"status": 403,
"detail": "This endpoint needs the orders:write scope."
}When to answer 404 instead of 403
A 403 confirms that something is there. Sometimes that alone is the secret: whether a user with a given email address has an account, whether a company has a project called "acquisition", whether a private repository exists. RFC 9110 explicitly allows a server that wants to hide a forbidden resource to answer 404 instead.
GitHub does exactly this. Its API returns 404, not 403, for a private repository the caller cannot see, so the response is the same whether the repository is private or was never created.
- Use 404 when the resource's existence is sensitive, typically when its identifier is guessable or meaningful - names, email addresses, sequential IDs.
- Use 403 when the caller already knows the resource exists, for example they can read it and are trying to delete it. Hiding it then only makes the error harder to understand.
- If you hide, hide completely: return the same status, body and headers for "does not exist" and "exists but forbidden". A different error message, or a response that is reliably slower in one case, gives the secret away again.
The order of checks
Getting the status right is mostly about checking things in the right order:
- Authenticate. No credentials, or invalid ones: 401, before anything else is looked up.
- Find the resource. If it does not exist: 404.
- Authorise. If the caller may not see it and its existence is sensitive: 404. If they may not perform this action on it: 403.
- Otherwise, do the work.
Step one comes before step two on purpose. If an anonymous caller gets 404 for a missing resource but 401 for an existing one, the difference between the two answers tells them which resources exist without ever logging in.
Codes that get confused with these three
- 400 Bad Request: the request itself is malformed, such as an
Authorizationheader in a format the server cannot parse at all. - 407 Proxy Authentication Required: the 401 of a proxy between client and server, with
Proxy-Authenticatein place ofWWW-Authenticate. - 410 Gone: the resource existed and was removed on purpose, and will not come back. Unlike 404, it is a statement that it is gone for good.
- 429 Too Many Requests: rate limiting, which a login endpoint needs. It is not a 403, because the same request will succeed later.
To see what an API actually returns, send the request with and without credentials from the API client, which shows the status and the response headers. Because it runs in the browser, it sees only the headers the API exposes to pages through Access-Control-Expose-Headers - if WWW-Authenticate is missing there, check with curl -i before concluding the server does not send it.
