Standardizing HTTP API error responses with Problem Details

Integrating with an HTTP API that you have no control over can be a challenge, particularly if the developers didn’t properly implement error handling. However, you can help solve this problem by using the Problem Details open standard for HTTP APIs.

The problem with HTTP APIs

Working with HTTP APIs can be a frustrating experience due to inconsistent naming, strange behavior, and poor error handling. All annoying stuff. In this article, we are focusing on correctly handling errors.

Here are two examples of terrible ways to return errors:

Inconsistent error responses: instead of returning the same JSON error object for every response, some developers return different objects or fail to provide a good error response at all. This can lead to confusion and frustration for API users.
Incorrect HTTP status response codes: returning a 200 OK response instead of an error code like 404 or 401 suggests a lack of understanding of the HTTP protocol. Modern front-end frameworks and libraries expect specific error status codes and help developers deal with these responses. By always returning 200, you’re creating more work for the users of your API.

Since APIs are usually consumed either by your colleagues or your customers, you should try to keep things as clear and consistent as possible in your API’s responses.

The ‘Problem Details’ standard

Many developers encounter the issues I listed above, which is why an official standard was created to solve these problems.

Problem Details for HTTP APIs is a specification that provides error details in a standardized format. It uses the format of a JSON object with specific keys and values to provide information about an error that occurred when processing a request. You can read the entire specification here: https://www.rfc-editor.org/rfc/rfc7807.

Here is an example of a problem details response for a request to an API endpoint that requires authentication, but the request is missing an authentication token:

```http request HTTP/1.1 401 Unauthorized Content-Type: application/problem+json

```json
{
	"type": "https://example.com/problems/authentication-required",
	"title": "Authentication Required",
	"status": 401,
	"detail": "The request is missing an authentication token.",
	"instance": "/api/v1/example"
}

Let’s go over the standard values we see in the example:

Type is the type of error encountered, you can link to a specific bit of documentation like the example above, that helps people debug their issue.
Title is a short description of the error that was encountered.
Status is the HTTP response status. Make sure to always use the most correct HTTP error status!
Detail is a longer, detailed description of the problem.
Instance specifies the resource that encountered the problem.

By adhering to the Problem Details standard, developers can easily write code to handle errors consistently. The base set of values, such as type, title, status, detail, and instance, should always be included in a problem details response. However, you are free to extend the JSON by adding what the standard calls ‘extensions’. These are any additional properties and values you want to add.

Here’s an example of a problem details response with extensions:

{
	"type": "https://example.com/problems/out-of-credit",
	"title": "You do not have enough credit.",
	"detail": "Your current balance is 30, but that costs 50.",
	"instance": "/account/12345/msgs/abc",
	"balance": 30,
}

In this case, an error is thrown because the user does not have enough credit to make a purchase. We added the ‘balance’ property as an extension.

In conclusion

By always returning errors in the Problem Details format, you get the following benefits:

As a developer consuming an HTTP API, you only need to write your error-handling code once, instead of creating custom code for each API.
As a developer of an HTTP API, you can save time by using the existing standard instead of creating your own error-handling system.
You are free to extend the standard by adding additional values and properties.