Error handling and code

The API returns HTTP error codes and a JSON payload whenever something goes wrong.

1 400 - Bad request
2 429 - Throttled
3 404 - Not found
4 500 - Internal error

400 - Bad request

This is the default error code that you will receive. The reason of error is included in the JSON returned. They key properties to look at are:

error.date: Date of this payload
error.title: The error message
error.details: May contain additional information such as a unique reference of the error
error.operation: With long running asynchronous operations this contains a title for the operation
error.messages: If this error contains child errors then you will find them here.
error.errorurl: You can disregard this element
reason: Same as error.title

Example with an API call accessing a document that does not exist:

{
  "error": {
    "operation": null,
    "date": "2020-12-15T08:34:38.7706101Z",
    "title": "The requested file does not exist.",
    "details": null,
    "errorurl": null,
    "messages": []
  },
  "reason": "The requested file does not exist."
}

Example of authentication attempt with invalid API key:

{
  "error": {
    "operation": null,
    "date": "2020-12-15T08:44:08.7986219Z",
    "title": "Invalid private key.",
    "details": null,
    "errorurl": null,
    "messages": []
  },
  "reason": "Invalid private key."
}

If your authentication token expired or is simply invalid, you will get an error like this:

{
  "error": {
    "operation": null,
    "date": "2020-12-15T10:00:45.4858252Z",
    "title": "Token invalid or expired.",
    "details": "Token invalid or expired.",
    "errorurl": null,
    "messages": [
      {
        "title": "Not authenticated",
        "details": "API construct session from token failed with error: Not authenticated",
        "errorurl": null
      }
    ]
  },
  "reason": "Not authenticated - API construct session from token failed with error: Not authenticated"
}

429 - Throttled

You receive this error when you reached the hourly allowance for API calls.

Note: Authentication API calls are not counted.

The error message contains information about the maximum allowance. It does not include information on when you can retry.

If you encounter such an error please wait for at least 10 seconds and try again.

If you consume your allowance within a very short time you will potentially have to wait for an hour. It is best to evenly spread API calls over the interval and reduce to a maximum the amount of calls to fit into the limits assigned to you.

404 - Not found

There may be different reasons for this:

You are calling an API method that does not exist or is announced but not yet released.
The API expects a mandatory URL parameter but you did not supply it. Or the an integer ID is expected in the URL path but you supply e.g. an alphanumeric sequence.

This error always points to an invalid end point or invalid URL parameters. Please consult the documentation. The documentation may also contain errors in which case please let us know through support!

500 - Internal error

You normally would not receive any error of this kind.

If however you do then the API service may be temporarily unavailable or there is a defect in our code. In such a case we would appreciate a message from you to support!