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

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.