In case you didn’t read the error message above, the part that matters says: Failed to execute ImportKey action in set service. Deleting created cart item. : 500 Internal Server Error

Yes, this is an actual error message from one of my team’s actual backend web applications. No, it doesn’t make any sort of sense; I totally agree with you.

In web development, we place a lot of emphasis on the “happy path”. The path that we want and expect our users to take when they’re using our tool or application — it’s the path we code for, the path we optimize for, the path we place most of our focus on.

The “unhappy path”, is the path when a user doesn’t do the right thing, click the right button, or generally figures out how to use the system in some way other than its intended purpose. This is the path where things go wrong, and with bad error messaging (like the above), we, as both users and developers, have a really hard time figuring out what exactly went wrong. And in general, the unhappy paths (and the errors they produce) are given a lot less thought about how they should be handled in an effective manner.

That needs to change. Here’s what I propose in the name of better error handling, all of which is based on the OData v4 JSON specification.

What is OData?

Before I give my recommendations, let me give a little background on OData.

OData stands for Open Data Protocol, and it is an open protocol which allows the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way. Microsoft initiated OData in 2007. — Wikipedia, OData

In essence, OData defines a set of best practices for building and consuming RESTful APIs (application program interface). These practices help developers focus on business logic while building RESTful APIs without having to worry about the various approaches to define things like request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options and more.

It proposes standards to make web development a little less haphazard and a little more predictable, regardless of programming language or development approach and team.

Now, we know about OData and its legitimacy and reason for being in the world, let’s get down to the rules of handling errors.

The 8 Error Rules To Follow

Below are the standards my team and wider company are working to enact with our applications — they’re generic enough recommendations to apply broadly to APIs in general, but specific enough to remove the questions around how to go about implementing the recommendations.

Rule 1: Code One, Reusable Error Handler

For nonsuccess conditions, developers SHOULD be able to write one piece of code that handles errors consistently across different REST API methods.

be able to write one piece of code that handles errors consistently across different REST API methods. This allows for the building of simple and reliable infrastructure to handle exceptions as a separate flow from successful responses.

Keep in mind, this error handler is very generic and does not require specific OData constructs. APIs SHOULD use this format even if they are not using other OData constructs.

Rule 2: The JSON Error Handler Must have an Error Object