When a Google Cloud IoT Core API request succeeds, the API returns an
HTTP 200 OK
status code along with the requested data in the body of the
response.
When a request fails, the Cloud IoT Core API returns an HTTP 4xx
or
5xx
status code that generically identifies the failure, as well as a response
that provides more specific information about the error that caused the
failure.
The rest of this page describes the structure of an error, enumerates specific error codes, and recommends how to handle them.
Error responses for JSON requests have the following structure:
{ "error": { "code": "integer", "message": "string", "status": "string", "details": array } }
The response object contains a single field error
whose value contains the
following elements:
Element | Description |
---|---|
code |
An HTTP status code that generically identifies the request failure. |
message |
Cloud IoT Core-specific information about the request failure. |
status |
The canonical error code (google.rpc.Code ) for Google APIs. Codes that may be returned by the Cloud IoT Core API are listed in Error codes. |
details |
Additional information, such as the type of error and/or a more detailed description of the cause. |
The following example shows an error response. The error
was returned because the request, in this case devices.publishEvent
,
contained an invalid payload:
{ "error": { "code": 400, "message": "Invalid value at 'binary_data' (TYPE_BYTES), Base64 decoding failed for \"123\"", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "fieldViolations": [ { "field": "binary_data", "description": "Invalid value at 'binary_data' (TYPE_BYTES), Base64 decoding failed for \"123\"" } ] } ] } }
Error codes and error handling
The recommended way to classify errors is by inspecting the value of the
canonical error code (google.rpc.Code
). In JSON errors, this code appears
in the status
field. In application/x-protobuf
errors, it's in the code
field. For many errors, the recommended action is to try the request
again using exponential backoff. For information on how to implement exponential
backoff in Cloud IoT Core, see Implementing exponential backoff.
Canonical error code | Description | Recommended action |
---|---|---|
ABORTED |
The request conflicted with another request. | Retry using exponential backoff. |
ALREADY_EXISTS |
The request attempted to create an entity that already exists. | Do not retry without fixing the problem. |
CANCELLED |
The operation was canceled, likely by the caller. | Retry using exponential backoff. |
DEADLINE_EXCEEDED |
A deadline was exceeded on the server. | Retry using exponential backoff. |
FAILED_PRECONDITION |
A precondition for the request was not met. The message field in the error response provides information about the precondition that failed. | Do not retry without fixing the problem. |
INTERNAL |
The server returned an error. | Retry using exponential backoff. |
INVALID_ARGUMENT |
The client specified an invalid argument. | Do not retry without fixing the problem. |
NOT_FOUND |
The request was attempted on an entity that does not exist. | Do not retry without fixing the problem. |
OUT_OF_RANGE |
The request exceeded the valid range. | Do not retry without fixing the problem. |
PERMISSION_DENIED |
The user was not authorized to make the request. To avoid revealing the existence of resources, if the user makes an unauthorized request on an entity that doesn't exist, this error is returned instead of NOT_FOUND . |
Do not retry without fixing the problem. |
RESOURCE_EXHAUSTED |
Either out of resource quota or reaching rate limiting. See Quota enforcement for more information. | Do not retry without fixing the problem. |
UNAVAILABLE |
The server returned an error. | Retry using exponential backoff. |
UNIMPLEMENTED |
The operation is not implemented or is not supported in the Cloud IoT Core API. | Do not retry. |
UNKNOWN |
The error is unknown. | Retry using exponential backoff. |