错误和错误处理

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

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

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

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 服务器返回错误。 使用指数退避重试。