Error Codes

A summary of errors that can be encountered when using our 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. An example error response body is shown below.

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

Field

Type

Description

error

string

A summary of what went wrong.

code

int

HTTP status code of the response.

help

string

Developer documentation link for more details.

400 - Bad Request

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

401 - Unauthorized

The user or the Service Account can not 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 operations using Access Tokens, make sure to get a new one before the previous one expires.

See our Authentication guide for more details.

403 - Forbidden

The user or Service Account does not have access to this resource. Make sure you have a sufficiently elevated role. A list of permissions granted by each role can be found on the Permissions page.

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

When creating a resource using our REST API, a few seconds will pass before the resource is available. To avoid a 404 response, implement a short delay of 1 second before requesting the resource.

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 many devices as quickly as possible. After running 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 get in touch with Support.

503 - Service unavailable

See 500 - Internal Server Error.

504 - Gateway timeout

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

Last updated