Disruptive Technologies Disruptive Developers

Errors

The following errors are shared accross all API endpoints listen in both the API Reference and the Sensor Emulator API.

Error Response Body

The body of the response contains some additional information about the error and typically looks like the following:

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

The “Error” text tries to narrow down exactly what went wrong, the “Code” is the HTTP Status Code of the response and the “Help” link takes the user to the description of the specific error on this page.


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 receieved 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 expire. See our Authentication Article for more details.

If you copy-pasted the curl command from the Interactive API Reference, then you will have gotten an Access Token which will only be valid for one hour. See the cURL Article to learn how to use it with a Service Account.


403 - Forbidden

Your User, or the Service Account that you are using, does not have access to this resource.

Make sure that you have access to the Project, or the Organization, that you are trying to access.

Roles

If you are trying to modify a Sensor, such as changing or adding a Label, make sure that you, or the Service Account used to make the request, have at least Project Developer access.

If you are trying to modify a Project, such as inviting a new user or transferring a Sensor to another Project, make sure that you, or the Service Account used to make the request, are a Project Administrator.

If you are trying to transfer a Sensor to another Project, make sure that you, or the Service Account used to make the request, are Project Administrator in both the Project you are transferring the Sensor out of, and the one you are targeting to transfer it to.


404 - Not Found

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

Double-check any path parameters, that they are correct and that they exist. When executing a “:” method, such as /projects/{PROJECT_ID}/devices:transfer, this error indicates that the Project with PROJECT_ID cannot be found, not that the devices slated for transfer was not found.

Please note that it might take a few moment from a resource is created until the change has propagated. So if you are trying to fetch a very recently created resource, please try again with exponential backoff and minimum 1s delay.


409 - Conflict

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

If you are trying to create a new Label with the same name as an existing one, or invite a Member to an Organization or Project who is already invited, then you will get this error.

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 in too short of a time frame.

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

Retry-After Header

When you exceed this limit, this error reponse 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, lets say that you are trying to read-modify-write a specific Label on a lot of Devices as quickly as possible. After having run 25 requests in 1 second, you will get a “429 - Too Many Requests” error response. In the response, you will get a Retry-After which will tell you to wait 4 seconds before retrying again.

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


500 - Internal Server Error

There has been an internal error in our services.

These type of errors are often intermittent and we recommend you retry the request with an exponential backoff with minimum 1s 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.