错误和错误处理

当 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 表示该请求与另一请求发生冲突。 对于非事务性提交：
重试该请求或设计实体结构以减少争用。

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

否则，请依照指数退避算法重试。
UNAUTHENTICATED 表示请求的身份验证凭据无效。 在解决问题之前，请勿重试。
UNAVAILABLE 服务器返回错误。 使用指数退避重试。