Structured error message for HTTP API

I am trying to improve my knowledge and understanding since I started working on Apache APISIX project rest RESTful HTTP API. For this, I have been reading and looking at the following sources:

  • Books: At the moment, I am perfecting the API Design Patterns. Expect a review soon.
  • youtube: I would recommend Eric Wilde’s channel. While some videos are better than others, they all focus on the API.
  • IETF RFCs: Most RFCs are not about APIs, but a friendly person has compiled a list of those that are.

Today, I want to introduce the “Problem Description for the HTTP API” RFC, aka, RFC 7807.


REST principle mandates to use HTTP state for communication. For errors, HTTP defines two categories: client errors, 4xxand server errors, 5xx,

Imagine a banking API that allows you to make transfers. If you try to transfer more funds to your account it should fail. Some HTTP status codes may fit:

  • 400 Bad Request: The server cannot or will not process the request because of something perceived as a client error.
  • 402 Payment Required: The request cannot be processed until payment has been made by the client. However, no standard usage convention exists, and various entities use it in other contexts.
  • 409 Conflict: The request conflicts with the current state of the target resource.

Here’s the first problem: HTTP status codes were specified for human-to-machine interaction via the browser, not for machine-to-machine interaction via the API. Therefore, selecting a status code that maps one-to-one to a use case is rarely straightforward. For the record, Martin Fowler favors 409 in our case.

Whatever the status code, the second problem is related to the error payload or, more precisely, its structure. The structure is unimportant if a single organization manages the client and the API provider. Even if a dedicated team develops each of them, they can align. For example, imagine a mobile app that calls its own API.

However, problems arise when a team decides to use a third-party API. The choice of response structure is important in this case because it is now considered part of the contract: any change from the provider could break customers. Even worse, the structure is likely to vary from provider to provider.

Therefore, a standardized error reporting structure:

  • Provides uniformity across providers
  • Increases API stability

RFC 7807

RFC 7807 aims to address the problem by providing a standardized error structure.

The structure is the following:

The RFC describes the areas:

  • "type" ,string) – a URI reference [RFC3986] that identifies the type of problem; This specification encourages that, when referenced, it provides human-readable documentation for the problem type (for example, using HTML). [W3C.REC-html5-20141028]) when this member is not present, its value is assumed "about:blank",
  • "title" ,string) – a concise, human-readable summary of the problem type; It should not change from incident to occurrence of a problem, except for localization purposes (for example, using Active Content interaction; see [RFC7231, Section 3.4],
  • "status" ,number,[RFC7231]Section 6) for this occurrence of the problem generated by the origin server.
  • "detail" ,string) – Typical human-readable explanation for this occurrence of the problem
  • "instance" ,string) – A URI reference that identifies the specific occurrence of the problem. It may or may not receive more information if it is referred to.

–member of a problem description object

The RFC provides the following example when a higher amount of money is required to make a banking transfer.

Sample: Additional funds required for banking transfer

An example

I’ll use one of my existing demos as an example. The demo highlights several steps to ease the process of developing your API.

In step 6, I want users to be registered, so I limit the number of calls in a time window if they are not authenticated. I have created a dedicated Apache APISIX plugin for this. After the number of calls has reached the limit, it returns:

HTTP/1.1 429 Too Many Requests
Date: Fri, 28 Oct 2022 11:56:11 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.15.0

{"error_msg":"Please register at https:\/\/\/register to get your API token and enjoy unlimited calls"}

Let’s structure the message according to RFC 7807.

RFC 7807 Message Structure


RFC 7807 doesn’t only help client developers. This is a tremendous help to API implementers as it provides quick guidelines to avoid reinventing the wheel on every project.

Move ahead

Leave a Comment