API CRAFT : ERROR HANDLING

Adequate error response is one of the key feature of a good API to make developer happy. This helps application developers to understand API behaviour in a better way and also helps them map the API error with the appropriate application error.  When I started engineering the “Error Handling” capability of APIs. I considered following two aspects Mapping of API exceptions to appropriate HTTP status code.

Mapping of API exceptions to appropriate HTTP status code

I almost mapped all application exceptions to appropriate HTTP status codes. Spring API had detailed all kind of HTTP Status codes here, which will help you decide which kind of application exception should result in which HTTP status code. For example if the user is trying call a post request with inappropriate data and the validation fails in server, it should in tern return a HTTP 400. HTTP 400 stands for bad request.  Again if the user trying to get the detail of an entity which is not present in database, the API should return a HTTP 404 status code. HTTP 404 is used for resource not found.

Response body with fine grained exception detail

I realized only HTTP status code will be confusing most of the time for developers. Think of a scenario where the user is tying create a student using POST method and he is providing various attributes like fname, lname, country, state, rollNo. There are problem with multiple attributes, in server the validations are failing and user does not have any idea what’s the actual problem. This is where we decided to provide the actual problem in response body. In some scenarios, the problem could just not be one, so we crafted our response body for error to have multiple error objects.

Some Examples