Error handling

All APIs use conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with the API servers.

Errors will be returned as Problem details according to the RFC 7231. This means:

• A HTTP status code is returned in the HTTP response header
• Error responses will be of the Content-Type application/problem+json
• Error responses will have each of the following keys:
  • type (string): A URL to a document describing the error condition.
  • title (string): A short, human-readable title for the general error type.
  • status (number): Conveying of the HTTP status code so that all information is in one place.
  • detail (string): An optional human-readable description of the specific error.

An example of an unauthorized API call may look like this:

{
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
    "title": "Unauthorized",
    "status": 401,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-b0b7d0586b67e3746511f2ca6e532f61-6cb726c347200a15-01"
    }
}

Validation errors, like invalid parameters, describes each error in an object array called errors with following properties:

• message (string): A human readable error description
• source (string): The invalid property or object, which belongs to the request object.

An example of an API call with invalid properties may look like this:

{
    "errors": [
        {
            "message": "The value of ValidTo must be greater than the value of ValidFrom.",
            "errorCode": 0,
            "source": "ValidTo"
        },
        {
            "message": "The culture 'xx-XX' is not supported.",
            "errorCode": 0,
            "source": "CultureSettings"
        }
    ],
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-1657049fd2bcacf80fb13a52d0babbc7-90cf89ccc0e99f75-01"
    }
}

See RFC 7807 for a detailed description.