Error Handling

Summary
Whenever an error occurs during the processing of a request a fault is returned instead of the regular response.
The error codes are structured in a hierarchy.
The following tables lists the possible error codes.

Error responses

Whenever an error occurs during the processing of a request a fault is returned instead of the regular response.  We recommend all clients to implement error handling in their software.  The different types of errors and exceptions are grouped in a hierarchy of error codes, so you can implement the handling of all errors of a certain type at once, instead of having to test each specific error.

Error codes are returned in a custom HTTP response header called ‘X-WS-ErrorCode’.  For clients using the SOAP protocol, the code is also present in the errorcode element of the SOAP fault detail element.

Recommended error handling implementation

Implement the error code hierarchy

The error codes are structured in a hierarchy.  For example, Client.Authentication.Username is a Client.Authentication error, which is a Client side error.  Error handling code should understand the different levels present in the error codes.  This enables a client to correctly handle any future error codes.  Suppose that we introduce a new error code ‘Client.Authentication.Foobar’, for example.  An application unfamiliar with this specific error code can still handle it as a Client.Authentication error, starting a new session by logging in again or presenting its end users with a suitable message.

Use only error codes for error detection

Error responses might contain more specific information besides the error code (ie.  ‘Input missing (Nickname)’ and ‘engine::identify_user_method::nickname_missing’).  Do not rely on (parts of) these detailed descriptions, as they may be changed.  Instead, use the error code (ie.  ‘Client.Authentication.Username’) for determining the type and origin of the error.

Error codes

The following tables lists the possible error codes.  Error codes are strings, structured hierarchically for easy error handling.

Client errors

Client General error, caused by the client.
Client.Authentication Authentication of the client has failed, the client is not logged in.
Client.Authentication.HostRestriction Authentication failed due to restrictions on hosts and/or ip addresses.
Client.Authentication.Password Authentication failed due to an incorrect password.
Client.Authentication.Username Authentication failed due to an invalid username.
Client.Authorization The client has been authenticated, but isn’t allowed to use the requested functionality.
Client.Input An error occurred due to a problem with the client’s input.
Client.Input.FormatIncorrect The input is invalid because one of the parameters contains a syntax error or is in an incorrect format.
Client.Input.Incomplete The input is invalid because one of the required parameters is missing or is incomplete.
Client.Input.Invalid The input is invalid because one of the parameters contains an invalid or disallowed value.
Client.Payment The request can’t be processed, because the user (or its account) doesn’t have sufficient balance/credits.

Server errors

Server General error, caused by the server.
Server.Data An error occurred while retrieving requested data.
Server.Data.NotFound The requested data isn’t available (for example, the requested address does not exist).
Server.Data.NotFound.Nbwo.EstimateUnavailable An accurate NBWO value can not be estimated for the specified address.
Server.Data.NotFound.Kadaster.NotDeliverable The requested result is not deliverable.  (kadaster can not deliver person information due to legal reasons)
Server.Data.PageNotFound The requested result page doesn’t exist.
Server.Unavailable An error occurred that causes the service to be unavailable.
Server.Unavailable.InternalError The service is unavailable due to an internal server error.
Server.Unavailable.Temporary The service is unavailable due to a temporary technical problem.