错误和错误处理

当 Datastore 模式 Firestore 请求成功时，API 将返回一个 HTTP 200 OK 状态代码，并在响应正文中随附请求的数据。

请求失败时，Datastore API 将返回一个 HTTP 4xx 或 5xx 状态代码，一般用来标识失败，另外还会返回一个响应，以针对导致失败的错误提供更具体的信息。

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

JSON 请求的错误响应结构如下：

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

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

元素	说明
`code`	HTTP 状态代码，一般用于标识请求失败。
`message`	有关请求失败的具体信息。
`status`	Google API 的规范错误代码 (`google.rpc.Code`)。错误代码中列出了 Datastore API 可能返回的代码。

JSON 请求的错误响应示例如下：

{
  "error": {
    "code": 400,
    "message": "Key path is incomplete: [Person: null]",
    "status": "INVALID_ARGUMENT"
  }
}

如果采用 application/x-protobuf 内容类型发出的请求导致错误，则将返回一个序列化的 google.rpc.Status 消息作为载荷。

错误代码

如需对错误进行分类，推荐的方式是检查规范错误代码 (google.rpc.Code) 的值。在 JSON 错误中，此代码出现在 status 字段中。在 application/x-protobuf 错误中，此代码出现在 code 字段中。

规范错误代码	说明	建议执行的操作
`ABORTED`	表示该请求与另一请求发生冲突。	对于非事务性提交：重试该请求或设计实体结构以减少争用。对于随transactional提交而发出的请求：重试整个事务或设计实体结构以减少争用。
`ALREADY_EXISTS`	表示请求尝试插入已存在的实体。	在解决问题之前，请勿重试。
`DEADLINE_EXCEEDED`	服务器超出了截止日期。	使用指数退避重试。
`FAILED_PRECONDITION`	表示未满足请求的先决条件。错误响应中的消息字段提供了未满足的先决条件的相关信息。一种可能的原因是正在运行的查询要求尚未定义的索引。	在解决问题之前，请勿重试。
`INTERNAL`	服务器返回错误。	不要多次重试此请求。
`INVALID_ARGUMENT`	表示请求参数的值无效。错误响应中的消息字段提供了无效值的相关信息。	在解决问题之前，请勿重试。
`NOT_FOUND`	表示请求尝试更新不存在的实体。	在解决问题之前，请勿重试。
`PERMISSION_DENIED`	表示用户无权发出请求。	在解决问题之前，请勿重试。
`RESOURCE_EXHAUSTED`	表示项目超出其配额或区域/多区域容量。	确认您没有超出项目配额。如果您超出了项目配额，则必须解决问题再重试。否则，请依照指数退避算法重试。
`UNAUTHENTICATED`	表示请求的身份验证凭据无效。	在解决问题之前，请勿重试。
`UNAVAILABLE`	服务器返回错误。	使用指数退避重试。