Error messages

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\""
          }
        ]
      }
    ]
  }
}

Note: Other than the value in the code element, the text of the error could change at any time. Therefore, applications should not depend on any non-code element text.

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.