Skip to main content

Errors

The dilisense API adheres to the regular HTTP error codes. This means that codes in the 2xx range indicate a successful API call, codes in the range of 4xx indicate an error on the client side (e.g. failed authentication, missing request parameter etc.) and codes in the 5xx range inform you about an error with the dilisense servers.

Status codes​

200 - OK - The request was successful.
400 - Bad Request - The request was incorrect, e.g. a mandatory parameter is missing or a parameter is not supported.
401 - Unauthorized - The API key was not valid.
403 - Forbidden - The URL is not accessible.
404 - Not Found - The requested resource does not exist, e.g. an unknown key ID.
429 - Too Many Requests - The request was throttled or your quota is exhausted.
500 - Internal Server Error - An internal error occurred.
503 - Service Unavailable - The servers are temporarily at capacity.

API responses with HTTP code 200 are the only ones that are charged.

Error format​

There is a detailed error message (JSON) available for each of the error responses, for example:

{
  "error_message": "The name parameter is mandatory, but has not been set."
}

Base your error handling on the HTTP status code, not on the text of the error message.

Throttling and quotas​

A 429 HTTP error code has one of two causes:

  • Throttling: your API key sent too many requests in a short time. The response carries a Retry-After header with the number of seconds to wait before retrying.
  • Quota exhausted: your API key reached one of its quotas. The response carries no Retry-After header, since retrying does not help until the quota period restarts or the quota is increased.

A 503 HTTP error code with a Retry-After header means that the dilisense servers are temporarily at capacity. Retry after the given number of seconds.

tip

Retry 429 and 503 responses with a Retry-After header after the given delay, and 500 responses with an exponential backoff. Do not retry other 4xx responses unchanged, they fail again.