CodePark/ questions / Status codes
START PRACTICINGPRACTICE
Backend question · HTTP & API design › Status codes

What is the difference between 401 Unauthorized and 403 Forbidden? When might you return 404 instead?

401 means "we don't know who you are". 403 means "we know who you are, but you are not allowed".

401 means the request has no valid authentication credentials. Examples are no token, an expired token or a wrong password. The name "Unauthorized" is misleading, because 401 is about authentication (proving who you are). A 401 response should include a WWW-Authenticate header. This header tells the client how to authenticate, for example with Bearer.

403 means the server refuses the action. The server knows who you are, or does not need to know. Logging in again will not help, because you do not have the permission.

Sometimes an API returns 404 instead of 403 to hide that a resource exists. For example, user A asks for user B's private document. Answering 404 does not reveal that the ID is valid. RFC 9110 explicitly allows this.

  • 401 means the client is not authenticated, or its credentials are invalid.
  • A 401 response should send a WWW-Authenticate header.
  • 403 means the client is authenticated, or authentication does not matter, but the action is not allowed.
  • 404 can hide that a resource exists.