错误消息

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

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

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

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`	未知错误。	使用指数退避重试。