Error Codes

A summary of Errors that can be returned by the REST API.

Response Body

The response body contains information about the error and typically contains the following three fields, but this may vary depending on the error.

  • error: Sums up what went wrong.

  • code: HTTP status code of the response.

  • help: Link to the developer documentation for a more detailed explanation.

An example response body is shown below.

{
"error": "already exists",
"code": 409,
"help":"https://docs.d21s.com/error/#409"
}

400 - Bad Request

Most likely due to an invalid argument as a part of a path, query parameter, or in the body of the request. Please see the error message for more information.

401 - Unauthorized

Your user, or the Service Account that you are using, cannot be authenticated towards our API.

Access Tokens

If you are using an Access Token received from our OAuth2 endpoint, please note that these are only valid for one hour. For uninterrupted operation using Access Tokens, make sure to get a new one before the previous one expires.

403 - Forbidden

Your user, or the Service Account that you are using, does not have access to this resource. Make sure your Service Account has the correct role, or elevate if necessary. A list of permissions granted by each role can be found under Managing Access Rights.

404 - Not Found

The resource that you are looking for doesn’t exist.

When executing a method in the form of/projects/{PROJECT_ID}/devices:transfer, where the last argument is separated by a :, this error indicates that the PROJECT_ID cannot be found, not that the devices slated for transfer were not found.

Propagation Delay

It should be noted that if you are creating a service through the API, let's say a new project, a few moments will pass before the newly created is available through the API. This is fixed by simply waiting for about a minimum of 1 second before calling the newly created service.

409 - Conflict

The resource that you are trying to create most likely already exists.

You will get this error if you are trying to create a new label with the same name as an existing one, or if you invite a member to an organization or project who is already invited.

It is also possible to get this error if you are trying to change a resource rapidly from different clients at once. If you suspect this, then read out the related resources again, apply any changes and try to do the operation again.

429 - Too many requests

You are sending too many requests to the API too quickly.

When you exceed your rate-limit of 75 requests per 10 seconds you will see this error. This represents a steady state of 7.5 requests per second, but we also allow for shorter bursts, up to the limit of 75 requests per 10 seconds.

Retry-After header

When you exceed this limit, this error response will have an attached Retry-After header. This header can be used to schedule a retry no earlier than the provided Retry-After value in seconds.

For example, let us say that you are trying to read-modify-write a specific label on a lot of devices as quickly as possible. After having run 75 requests in 1 second, you will get a “429 - Too many requests” error response. In response, you will get a Retry-After which will tell you to wait 9 seconds before retrying again.

Please note that while this burst-wait-burst is possible, spreading out requests over time is preferred.

500 - Internal server error

There has been an internal error in our services.

This error is usually intermittent, and we recommend you retry the request with an exponential backoff with a minimum 1-second delay.

If the error persists, please check our Status Page. If there is no announced downtime, please contact Support.

503 - Service unavailable

See 500 - Internal Server Error.

504 - Gateway timeout

See 500 - Internal Server Error, but retry with minimum 10s delay.