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.
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