26

I have found a lot of answers and explanations for the meanings of HTTP status codes. My question is specifically about the POST request to a login endpoint, which asks for username and password for example and the scenario where incorrect ones are provided.

Some thoughts:

400 Bad Response I think this code is not appropriate, because it says the request was syntactically incorrect and not understood by the server, which is not the case here. The login data is just semantically not correct.

401 Unauthorized Here is the tricky part for me. If 401 can only occur on requests requiring an authentication header then this is not correct. But if 401 can occur on all requests, which require authentication (either as header or in the body) then 401 is a candidate.

403 Forbidden Usually, 403 is returned if the user already is authenticated and known to the system but requested a resource he/she is not allowed to access. The user definitely is not authenticated before the login. I don't know if there is a semantic for 403 for unauthenticated users.

I'm happy to be told the answer or hear your thoughts.

6
  • Everything you have written seems to be correct and I do not see any questions Jul 27, 2017 at 17:14
  • 3
    the question is in the title
    – Peter F
    Jul 27, 2017 at 17:15
  • 1
    Throw 'em a teapot error. Why give hackers any information?
    – user1228
    Jul 27, 2017 at 17:18
  • short answer: 401, long answer is in your question Jul 27, 2017 at 17:18

3 Answers 3

35

If a user is attempting to authenticate, but provides invalid credentials, the response should have a status of 401, regardless of if you are using Basic Authorization or not. 401 indicates that authentication failed, but the user can alter their request and attempt again.

If a user is authenticated, but not authorized to access the requested resource, then the response should have a status of 403. 403 indicates that the user is forbidden from accessing the resource, and no matter how they alter the request, they will not be permitted access.

In the scenario that your endpoint requires the credentials to be in the body of the request, you should return a 400 if the request body does not meet your specifications.

4
  • is there any documentation for this? I mean who says we can't send 200 status code in response and mention the reason in body? (I know it's not a good practice but I'm looking for a book or reference) Jan 9, 2022 at 4:44
  • Here is the specification: w3.org/Protocols/rfc2616/rfc2616-sec10.html Jan 9, 2022 at 15:53
  • Ultimately, you can design your endpoints however you want, and document accordingly. However, following a well-known standard will surprise your clients the least, and may even allow them to reuse some of their existing code. Jan 9, 2022 at 15:58
  • Yeah always I have an argue with some developers who say better we reply 200 status code but in body we can reply a defined model with result that says authentication has failed for this reason! thanks Joshua Jan 10, 2022 at 3:18
4

My question is specifically about the POST request to a login endpoint, which asks for username and password for example and the scenario where incorrect ones are provided.

It depends on how the credentials are sent:

  • If you are using HTTP Authentication (sending credentials in the Authorization header), you can return 401 to indicate that the credentials are invalid.

  • If you send credentials in the request body (for example a JSON with username and password), 401 doesn't seem to be the most suitable status code (once it's not a real HTTP Authentication). In this situation, consider 403 instead with a descriptive response payload.


The 403 status code also can be used to indicate authorization problems, that is, to indicate that a user is not allowed to perform an action.

1
  • 2
    For the second bullet: 403 is Unauthorized and depends on the role or claims a user has which may be unsufficient for specific endpoints/resources and has nothing to do with credentials unknown to the api. In case of unknown combination username/password a 401 should be returned instead of 403. And the misleading thing is that 401 is labeled as Unauthorized as it should state Unauthenticated and 403 Forbidden is actually Unauthorized. Sep 20, 2019 at 15:37
2

401 for invalid credentials when using HTTP Authentication

403 for user logged in but attempting to access area that is not allowed

2
  • 401 for invalid credentials is not quite accurate. It should be: 401 for invalid credentials when using HTTP Authentication Jul 31, 2017 at 8:27
  • 1
    True! Thanx, Cássio I've updated the answer to clarify.
    – fv_dev
    Jul 31, 2017 at 13:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.