状态响应代码

gRPC 响应可返回以下状态代码。本网站上的所有 gRPC 版本均适用。

代码 状态 备注
0 OK 返程日期:Success
1 CANCELLED 操作已取消(通常是被调用者取消)。
2 UNKNOWN 例如,当从其他地址空间接收到的 Status 值属于此地址空间中未知的错误空间时,可能就会返回此错误。此外,由未返回足够错误信息的 API 引发的错误也可能会转换为此错误。
3 INVALID_ARGUMENT 客户端指定的参数无效。
4 DEADLINE_EXCEEDED 截止时间已过,操作尚未完成。对于更改系统状态的操作,即使操作已成功完成,也可能会返回此错误。例如,来自服务器的成功响应,响应延迟太久,以致截止期限已过。
5 NOT_FOUND 未找到所请求的某些实体。
6 ALREADY_EXISTS 客户端尝试创建的实体已存在。
7 PERMISSION_DENIED 调用方无权执行指定的操作。如果遭拒的原因是部分资源已用尽,请勿使用 PERMISSION_DENIED;请改用 RESOURCE_EXHAUSTED 来表示此类错误。如果无法识别调用方,请勿使用 PERMISSION_DENIED(请改用 UNAUTHENTICATED 来表示这些错误)。收到 PERMISSION_DENIED 错误代码并不意味着请求有效、请求的实体存在或满足其他前提条件。
8 RESOURCE_EXHAUSTED 部分资源已用尽,可能是每用户配额不足,也可能是整个文件系统的存储空间已用完。
9 FAILED_PRECONDITION 操作被拒绝,因为系统未处于执行该操作所需的状态。 例如,要删除的目录非空,或者将 rmdir 操作应用于非目录。
10 ABORTED 操作已中止,通常是由于序列程序检查失败或事务中止等并发问题。
11 OUT_OF_RANGE 尝试执行的操作已超出有效范围。
12 UNIMPLEMENTED 操作在此服务中未实现或不受支持/未启用。
13 INTERNAL 内部错误。这意味着底层系统所期望的一些不变量已损坏。此错误代码仅用于严重错误。
14 UNAVAILABLE 该服务目前不可用。 这很可能是一种暂时情况,可以通过退避重试来纠正。
15 DATA_LOSS 数据丢失或损坏且不可恢复。
16 UNAUTHENTICATED 请求没有相应操作的有效身份验证凭据。

有时可能适用多个错误代码。服务应返回适用且最具体的错误代码。例如,如果 OUT_OF_RANGEFAILED_PRECONDITION 都适用,请优先使用这两个代码。同样,优先使用 NOT_FOUNDALREADY_EXISTS,而非 FAILED_PRECONDITION

FAILED_PRECONDITION、ABORTED 与 UNAVAILABLE

以下石膏测试可帮助您在 FAILED_PRECONDITIONABORTED 还是 UNAVAILABLE 之间做出选择:

  • 如果客户端只能重试失败的调用,请使用 UNAVAILABLE
  • 如果客户端应在更高层级重试(例如当客户端指定的测试和设置失败(指示客户端应重启读取-修改-写入序列)时,请使用 ABORTED
  • 如果客户端在系统状态得到显式修复之前不应重试,请使用 FAILED_PRECONDITION。例如,如果“rmdir”因目录非空而失败,则最好返回 FAILED_PRECONDITION,因为除非从目录中删除文件,否则客户端不应重试。

INVALID_ARGUMENT、FAILED_PRECONDITION 与 OUT_OF_RANGE

以下石膏测试可帮助您在 INVALID_ARGUMENTFAILED_PRECONDITION 还是 OUT_OF_RANGE 之间做出选择:

  • 如果无论系统的状态如何,参数都有问题,请使用 INVALID_ARGUMENT。例如:网址格式不正确
  • 如果值因系统状态而超出范围,请使用 OUT_OF_RANGE。例如,start_date 早于 start_date_restrict
  • 如果因系统状态而导致值无效,但该值并非 OUT_OF_RANGE 值,请使用 FAILED_PRECONDITION