0

I am developing a web application and struggling to follow a clear semantic while returning response to the client. Taking an example of authenticating an user there can be following scenarios:

1. Request is successful

The user is authenticated and I send a JSON response

{success: true} // and an optional message field?

2. An application error occurred

User is not authenticated.

{error: true, message: 'Invalid email or password'} // Again I am not sure if I should let client decide to show the error message

3. System error

Bad SQL query, DB crashed etc. typically server should return 500 status code but should I again send the JSON response with it? if yes, how much should I tell the client? because the client or user may not be interested in knowing that DB crashed or SQL was not well formatted.

Any other suggestion/modification is most welcome.

4

I am developing a web application and struggling to follow a clear semantic while returning response to the client. Taking an example of authenticating an user there can be following scenarios:

1. Request is successful

The user is authenticated and I send a JSON response

{success: true} // and an optional message field?

If in doubt, D.R.Y.

As a client to a REST service, an empty 204 response is quite enough to indicate that everything worked and that the client doesn't need to do anything else.

2. An application error occurred

User is not authenticated.

{error: true, message: 'Invalid email or password'} // Again I am not sure if I should let client decide to show the error message

A client will usually expect authentication/authorisation errors to be handled with a 401 response. No additional information is needed; in fact, the less information you provide is less information available to a potential intruder who is trying to guess different potential username and password combinations.

Other types of errors, such as a badly formatted query string, errors in the HTTP request body, or validation failures would typically return 400 Bad Request.

In the case of 400 Bad Request, it is certainly worth returning a response with detailed information which describes exactly how the request might be wrong - whether it's an issue with the structure of the data, the data format, a missing field, a validation error, some unexpected information, etc.

As a client to a REST service the quality of the message and detail provided in a 400 error response can be the difference between hours/days of frustrating trial-and-error debugging versus a quick 5-minute bugfix.

3. System error

Bad SQL query, DB crashed etc. typically server should return 500 status code but should I again send the JSON response with it? if yes, how much should I tell the client? because the client or user may not be interested in knowing that DB crashed or SQL was not well formatted.

A simple 500 Internal Server Error response is all you need here. A client cannot do anything about a bug in the server code, nor the fact that the database crashed or the server failed in some unexpected way. When a client receives '500' the only sensible thing for that client to do is simply to give up (and maybe try again much later..)

Information about server-side errors are important to whoever looks after the server, so the best place for that information is your server-side logs.

Time spent trying to send information back to a client would be much better served by ensuring the logs contain detailed information which allow somebody to debug the server.


In general

Don't return your own hand-rolled JSON error status flags from a REST API for scenarios which are already handled by well-known HTTP status codes. HTTP client libraries are generally already capable of handling those return codes, so not only are you potentially reinventing the wheel on the server and making your API unnecessarily complex with extra objects and fields, you're probably also forcing the client to do the same, and making unnecessary extra work on the client side too.

2

1 Using HTTP Response status code

Whether for communicating a successful or error response in web applications, it is highly desirable (from the client and the developer point of view) to use the HTTP Response status code catalogue. Often, flags such as success:true or error:true are addressed to provide the exactly the same feedback that HTTP status codes provide, with the inconvenient of being only useful (or meaningful) for us.

The purpose of the flags is to decide whether the HTTP request has been successfully completed or not and to split the code into two possible execution paths. However, if we use the proper HTTP response status code, we find that most of the HTTP clients already do it for us.

AngularJS 1.5 (Jquery based) (Documentation)

$http.({...})
.then(function (response){
    // OK (2xx)
     ...
})
.catch(function (error){
    // KO (5xx , 4xx)
    ....
});

Jquery (Documentation)

$.ajax({...}) 
.done(function() {
  // OK (2xx)
})
.fail(function() {
   // KO (5xx , 4xx)
})  
.always(function() {
   // Both
});

2 Error messages

I agreed the user doesn't need to know that the DB crashed. Usually, these errors are rare, so a generic message is all the user need to know:

The request could not be processed due to internal errors. Please, try it later or contact the .....

From the security point of view, avoid providing the response with too many details. Some details could be used to look for vulnerabilities. Reducing the info we also can reduce the attack surface.

Back to the 2nd example, Invalid email or password. That's a good example of a generic message. Just do it much more "web compliant" returning the message with a 401 status code.

3 Handling error implementation

How to return a custom message for every possible error (exception) depends on the framework or the SDK. However, the approach uses to be: catch the error as late as possible. Let's say, for instance, in the controller. The controller usually has access to the response, so we could write the custom message and the HTTP status code from there.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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