Error handling

We can distinguish between two types of errors:

Client side errors
Server side errors

In both cases an appriopriate HTTP status code is returned and the request body will always contain a standard error object:

{
    "code":"error_code",
    "message":"Description of the error.",
    "_metadata": { Optional custom object containing extra information regarding the error },
    "_moreInfo": "{url to more detailed information}"
}

The error code is a machine-friendly code which can be used to automaticaly determine the appropriate action. The message is used to inform the developer of what went wrong in plain language. The metadata can optionally contain an object with extra information. If resources return extra metadata, they will be documented with the resource.

Client side errors

In case of a client side error four types of HTTP status codes can be returned:

HTTP 400 Bad Request
HTTP 401 Unauthorized
HTTP 403 Forbidden
HTTP 404 Resource Not Found
HTTP 405 Method Not Allowed

Errors specific to resources are documented with each resource, all posible error codes are listed. Validation errors like missing fields or invalid values are NOT documented with each resource. In case of validation errors a 400 Bad Request is returned with error code 'validation_error'. The metadata will contain detailed information about which fields contain errors:

{
    "code":"validation_error",
    "message":"One or more validation errors occurred.",
    "_metadata":
        [
            {
                "field":"Username",
                "message":"Username is required"
            }
        ]
}

Server side errors

We try our best to have a sensible response for every request. In case something goes wrong which we haven't anticipated we respond with a HTTP 500 internal server error. The response body consists of the same error object as for client side errors:

{
    "code":"unknown_error",
    "message":"An unknown error occurred. The error is logged with id '9fa9f756-f7a5-4e5e-91e8-950a99bb775f', please supply this identifier when contacting support.",
    "_metadata":
        {
            "errorId":"9fa9f756-f7a5-4e5e-91e8-950a99bb775f"
        }
}

The metadata contains the unique identifier of the error. Please supply this identifier when contacting us for support. It will help us locate the error quickly.