One area of RESTful web API design that's quite frequently overlooked is how to report errors and problems, either related to the business or application. The proper usage of the HTTP status codes comes to mind first, and although quite handy, it is often not informative enough. Let us take 400 Bad Request as an example. Yes, it clearly states that the request is problematic, but what exactly is wrong?
The RESTful architectural style does not dictate what should be done in this case and so everyone is inventing their own styles, conventions, and specifications. It could be as simple as including an error message in the response or as shortsighted as copy/pasting long stack traces (in case of Java or .NET, to name a few cultprits). There is no shortage of ideas but luckily, we have at least some guidance available in the form of RFC 7807: Problem Details for HTTP APIs. Despite the fact that it is not an official specification but a draft (still), it outlines some good common principles on the problem at hand and this is what we are going to talk about in this post.