9.4. Error messages SOAP and REST

The information in this chapter is described with the REST architecture principles in mind. One of the key elements of that architecture is the fact that data exchange is based directly on the HTTP protocol, and does not use an intermediate layer for functions or methods like SOAP. Create, read, update and delete functions translate directly into the HTTP methods POST, GET, PUT and DELETE.

When successful processing is not possible, an error situation occurs. Error situations can have many causes, which can be divided into two groups.

The first group is represented by the HTTP 4xx response status codes and indicates the error is caused by the client who is using the API. The best known example in this category is probably the 404 – Not Found error that everyone has encountered at some point when a website link is (no longer) valid. But many other codes are available which can be used to inform the client what went wrong, and where. This enables the client to address the problem and try again. To help the process of troubleshooting, analysis and diagnosis, it is highly recommended to supply additional information on possible causes and solutions. To this end the error response can be fitted with a body section that contains extra information and/or links to such information.

The second group holds HTTP 5xx errors for which the cause lies within the environment of the server where the API is hosted. These are in general access problems caused by the technical infrastructure (e.g. incorrect routing) or capacity problems caused by lack of bandwidth, server processor or memory capacity. When the client encounters this kind of error, the problem most likely lies on the receiving end at the server, and there is not much that can be done except wait and retry later.

In the context of the API-framework the use of HTTP status codes is recommended, these are described briefly below.

Success (2xx)

In a ‘happy flow’, a request is acknowledged with a status code in the 2xx series. The API-framework uses the following codes:

200 Ok
This is the generic, most commonly used code to indicate that a request has been received successfully; no errors have been encountered in transmission, and no apparent errors have been found in the technical message structure. It is the typical response for a function that overwrites or changes an existing dataset, and in those cases, it requires no additional information in the header or body of the response message.

It is also used after successful execution of a retrieve function, but in that case a (recurring) dataset is added in the response message to reflect the information of the provided id(s).

204 No Content
In a situation where a query was executed and the result is empty, the 204 code is used to indicate that the request has been well received and processed, but that no data was found. This is the preferred solution compared to the generic ’404 – not found’ error code because it is not necessarily an error situation.

Client errors (4xx)

401 Unauthorized or 403 Forbidden should be used for errors caused by the API client which are related to authentication and authorization.

404 Not found should be used in case data was not found because of a request for non-existing data, for example a non-existing attribute.

400 Bad Request should be used in all other cases.

Because of the generic nature of this error status, the response may contain additional information to help a client determine the cause of an error. This can be done by adding the information described in the table below. Even though the http status code is already present in the response header, we recommend providing it in the additional error information, as well. This makes the response body self-containing to support further (automatic) processing and troubleshooting.

JSON example

You can find examples of different HTTP return codes in chapter Examples of domain specific functions.