RESTful Login Failure: Return 401 or Custom Response

HttpRestLoginHttp Response-Codes

Http Problem Overview

This is a conceptual question.

I have a client (mobile) application which needs to support a login action against a RESTful web service. Because the web service is RESTful, this amounts to the client accepting a username/password from the user, verifying that username/password with the service, and then just remembering to send that username/password with all subsequent requests.

All other responses in this web service are provided in a JSON format.

The question is, when I query the web service simply to find out whether a given username/password are valid, should the web service always respond with JSON data telling me its successful or unsuccessful, or should it return HTTP 200 on good credentials and HTTP 401 on bad credentials.

The reason I ask is that some other RESTful services use 401 for bad credentials even when you're just asking if the credentials are valid. However, my understanding of 401 responses are that they represent a resource that you are not supposed to have access to without valid credentials. But the login resource SHOULD be accessible to anyone because the entire purpose of the login resource is to tell you if your credentials are valid.

Put another way, it seems to me that a request like: 

should return 401 if bad credentials are provided. But a request like:

should never return 401 because that particular URL (request) is authorized with or without valid credentials.

I'd like to hear some justified opinions one way or the other on this. What is the standard way of handling this, and is the standard way of handling this logically appropriate?

Http Solutions

Solution 1 - Http

First off. 401 is the proper response code to send when a failed login has happened.

>401 Unauthorized Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.

Your confusion about, sending back 401 when you just do a check, I think is based on the fact that doing boolean requests in REST often is wrong by the RESTful constraints. Every request should return a resource. Doing boolean questions in a RESTful service is a slippery sloop down to RPC.

Now I don't know how the services that you looked on are behaving. But a good way of solving this is to have something like an Account object, that you try to GET. If your credentials are correct, you will get the Account object, if you don't want to waste bandwidth just to do a "check" you can do a HEAD on the same resource.

An Account Object is also a nice place to store all those pesky boolean values that otherwise would be tricky to create individual resources for.

Solution 2 - Http

401 should be sent only when the request needs authorization header field and authorization fails. Since the Login API doesn't require authorization, hence 401 is the wrong error code in my opinion

As per the standard here

*10.4.2 401 Unauthorized

The request requires user authentication. The response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource. The client MAY repeat the request with a suitable Authorization header field (section 14.8). If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user SHOULD be presented the entity that was given in the response, since that entity might include relevant diagnostic information. HTTP access authentication is explained in "HTTP Authentication: Basic and Digest Access Authentication" [43].*

Solution 3 - Http

If the 401 response code is misleading for user authentication, the API can send HTTP status code 200 OK for both successful and failed authentication, but set a custom header on the authentication successful response and omit that header on failed logins.

The client can check if the header exists or not and decide the action.

Example: SpringBoot API Response

The call to OK when login is successful sets the header "gotyouin" with a value (anything). Call to failed does not add the header and client can treat this as a failed login attempt.

public class LoginResponseEntityHelper {
   public static ResponseEntity<?> ok(String token) {
	   return ResponseEntity.status(HttpStatus.OK).header("gotyouin", token).body(null);

    public static ResponseEntity<?> failed() {
	    return ResponseEntity.status(HttpStatus.OK).body(null);

Solution 4 - Http

Return 409 with a proper error message.


All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionMattView Question on Stackoverflow
Solution 1 - HttpClericView Answer on Stackoverflow
Solution 2 - HttpvinksharmaView Answer on Stackoverflow
Solution 3 - HttpAVVView Answer on Stackoverflow
Solution 4 - HttpshrimpwagonView Answer on Stackoverflow