As explained in the first section, 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. If these functions are executed, the API uses the available standard HTTP status codes in the 2xx range to indicate of the request.

When successful processing is not possible, an error situation occurs. There can be many root causes for this, which can be divided into two groups.

The first group is represented by the HTTP 4xx statuses and indicates that the error is caused by the client who is using the API. The best known example for this is probably the 404 – Not Found error that everyone has encountered at some point when a website link is (no longer) valid. But there are many other codes 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 diagnose, 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 problems in the technical infrastructure like incorrect routing, or capacity problems caused by lack of bandwidth or server processor or memory capacity. When the client encounters this kind of error, the problem lies most likely 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 a number 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.

An exception is a situation where the message is handled successfully, but the subsequent processing of the content is not. For example when the submitContainer function successfully delivers the container and content, but one or more messages can not be delivered because the receiver is (no longer) present on the platform. Or when the changeContainer function is used to retract a container and not all messages can be retracted.
In such cases, the response message may contain additional information in the response body to inform the client about the fact that the subsequent processing has not entirely been successful. The use of error information in these situations is described in detail in the respective paragraphs.

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).

The 200 code can also be used after the creation of a new dataset that was submitted, but 201 is more precise.
Using 201 also allows to differentiate from the situation where the message has been well received, but will take more time to process than the available time frame. In that situation the 202 code can be used to avoid a time-out error.

201 Created
For a positive result for the creation of a new dataset that was submitted the generic 200 code can be used, but 201 is the preferred option.
For both the 200 and 201 status the response header will contain an uri for the newly created item.
A response body is not required, but may optionally be added to include (part of) the newly created dataset.

202 Accepted.
This code is used for a temporary status and signifies that the message has been well received, but will take some time to process. The final result can be obtained by the client by polling, which is a pull action from the client. The alternative is a push action from the server, sending a notification to a dedicated API in the client environment.

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 autorization.

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, it may additionally be repeated in the additional error information. This makes the response body self-containing to support further (automatic) processing and troubleshooting.

Name Req. Type Description
error R entity Entity for error handling and support.
httpStatus integer HTTP status code.
errorCode R AFDERR Error code.
errorDescription R string Description of the error.

JSON example

400 Bad request

	"httpStatus": "400",
	"errorCode": "0001",
	"errorDescription": "Invalid JSON format"

A part of the new AFD codelist AFDERR is shown below. In the individual function chapters, specific causes for that function will be detailed if applicable.
Codes 0001 to 0999 are reserved for general use and are maintained by SIVI. Codes between 1000 and 9999 are available for parties exposing an API.

Group Code Description
General 0001 Invalid JSON format
General 0002 Invalid parameter
General 0010 Unknown senderId
MEP 0011 Unknown receiverId
MEP 0012 Roaming not supported for this mepId
MEP 0013 Message already retrieved by receiver

Server errors (5xx)

Any and all standard HTTP codes apply without restriction or additional information.


Thanks for your feedback.

Post your comment on this topic.

Post Comment