Handling errors in a client/server application

Question

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.

Answer 1

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.

Answer 2

1 Using HTTP Response status code

When working with web applications, it is preferable implementing HTTP Response status code catalogue to communicate the resolution of the requests and, somehow, the resolution of the business operation involved.

If the purpose of the flag is communicate whether the business operation finished successfully or not and fork the execution path, you will find that many HTTP clients already do that for you. It tooks choose the adecuate HTTP to make the client behave as desired.

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

Users don't need to know that the DB crashed. Some don't even know what's a DB, so a generic message is all they need to know

The request could not be processed. Please, try it later or contact the .....

From the security point of view, avoid providing the response with sensible details because these could be used to look for vulnerabilities.

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

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 can write the message and choose the HTTP status code from there.