Error Handling

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.

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.

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

Client errors

Server errors