oktools

401 vs 403 vs 404: Which Status Code Should Your API Return?

The difference between "who are you?", "you may not" and "there is nothing here", what the standard requires each response to carry, and when answering 404 for a forbidden resource is the right call.

The short answer

StatusMeansWould other credentials help?Must include
401 Unauthorized"Who are you?" No valid credentials came with the requestYes - send valid onesA WWW-Authenticate header
403 Forbidden"I know who you are, and no." The request is understood and refusedNot the ones sentNothing required
404 Not Found"There is nothing here" - or nothing the server is willing to admit toNoNothing 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:

Response
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_scope and 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:

Response
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:

  1. Authenticate. No credentials, or invalid ones: 401, before anything else is looked up.
  2. Find the resource. If it does not exist: 404.
  3. Authorise. If the caller may not see it and its existence is sensitive: 404. If they may not perform this action on it: 403.
  4. 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 Authorization header in a format the server cannot parse at all.
  • 407 Proxy Authentication Required: the 401 of a proxy between client and server, with Proxy-Authenticate in place of WWW-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.