错误消息

当 Google Cloud IoT Core API 请求成功时,API 会在响应正文中返回 HTTP 200 OK 状态代码以及请求的数据。

请求失败时,Cloud IoT Core API 会返回 HTTP 4xx5xx 状态代码,一般用来标识失败,另外还会返回一项响应,用于提供有关导致失败的错误的更具体信息。

本页的其余部分介绍错误的结构、枚举特定的错误代码,并提供相应的处理方法建议。

JSON 请求的错误响应具有以下结构:

{
  "error": {
    "code": "integer",
    "message": "string",
    "status": "string",
    "details": array
  }
}

响应对象包含单个字段 error,其值包含以下元素:

元素 说明
code HTTP 状态代码,一般用于标识请求失败。
message 有关请求失败的 Cloud IoT Core 专用信息。
status Google API 的规范错误代码 (google.rpc.Code)。错误代码中列出了 Cloud IoT Core API 可能返回的代码。
details 其他信息,例如错误类型和/或更加详细的原因。

以下示例显示了错误响应。之所以返回错误,是因为请求(在本例中为 devices.publishEvent)包含无效的载荷:

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

错误代码和错误处理

要对错误进行分类,推荐的方式是检查规范错误代码 (google.rpc.Code) 的值。在 JSON 错误中,此代码出现在 status 字段中。在 application/x-protobuf 错误中,错误出现在 code 字段中。对于许多错误,建议的操作是使用指数退避算法再次尝试请求。如需了解如何在 Cloud IoT Core 中实现指数退避算法,请参阅实现指数退避算法

规范错误代码 说明 推荐执行的操作
ABORTED 该请求与另一请求冲突。 使用指数退避重试。
ALREADY_EXISTS 该请求尝试创建的实体已存在。 在解决问题之前,请勿重试。
CANCELLED 调用者已取消操作。 使用指数退避重试。
DEADLINE_EXCEEDED 服务器超出了截止日期。 使用指数退避重试。
FAILED_PRECONDITION 不符合相应请求的先决条件。错误响应中的消息字段提供有关失败的前提条件的信息。 在解决问题之前,请勿重试。
INTERNAL 服务器返回一个错误。 使用指数退避重试。
INVALID_ARGUMENT 客户端指定的参数无效。 在解决问题之前,请勿重试。
NOT_FOUND 尝试对不存在的实体发出请求。 在解决问题之前,请勿重试。
OUT_OF_RANGE 请求超出了有效范围。 在解决问题之前,请勿重试。
PERMISSION_DENIED 用户无权发出该请求。为避免泄露资源的存在,如果用户对不存在的实体发出了未经授权的请求,系统会返回此错误,而不是 NOT_FOUND 在解决问题之前,请勿重试。
RESOURCE_EXHAUSTED 资源配额不足或达到速率限制。如需了解详情,请参阅配额执行 在解决问题之前,请勿重试。
UNAVAILABLE 服务器返回一个错误。 使用指数退避重试。
UNIMPLEMENTED Cloud IoT Core API 未实现或不支持该操作。 不重试。
UNKNOWN 未知错误。 使用指数退避重试。