Errors

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. 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.
Was this page helpful? Let us know how we did:

Send feedback about...

Google Cloud Internet of Things Core