状态码 (Status Codes)

概述

所有的 RPC 调用都会返回一个状态给客户端。状态对象由一个整数代码和一个字符串错误描述组成。服务器端（或用于库级错误的 gRPC 库）选择返回给定 RPC 的状态。应用程序应该仅使用以下定义的状态值。

当发生错误时，gRPC 库可能会生成相应的状态。库可以在客户端或服务器端生成状态。只有一小部分预定义的状态码是由 gRPC 库生成的。这使得应用程序可以确信它看到的任何其他代码实际上是由应用程序返回的（虽然服务器端也可能返回一个由 gRPC 库生成的状态码）。

有关如何使用状态码，请参阅《错误处理用户指南》。

完整的状态码列表

gRPC 使用一组明确定义的状态码作为 RPC API 的一部分。

以下状态码仅由用户代码生成，而不是由库生成：

INVALID_ARGUMENT
NOT_FOUND
ALREADY_EXISTS
FAILED_PRECONDITION
ABORTED
OUT_OF_RANGE
DATA_LOSS

状态码详情

Code Id 描述

Code	Id	描述
OK	0	不是错误，表示操作成功。
CANCELLED	1	操作已被取消，通常是由调用方取消的。
UNKNOWN	2	未知错误。例如，如果从另一个地址空间接收到的状态值属于一个在当前地址空间未知的错误空间，可能会返回此错误。也可能是 API 返回的错误信息不足时转换为此错误。
INVALID_ARGUMENT	3	客户端指定了一个无效的参数。请注意，这与 `FAILED_PRECONDITION` 不同。`INVALID_ARGUMENT` 指的是不论系统状态如何，都存在问题的参数（例如，文件名格式错误）。
DEADLINE_EXCEEDED	4	操作在完成之前超出了截止时间。对于会改变系统状态的操作，即使操作成功完成，也可能返回此错误。例如，服务器的成功响应可能已经延迟到超出截止时间。
NOT_FOUND	5	请求的实体（例如，文件或目录）未找到。注意：如果整个用户类的请求被拒绝，例如渐进式功能发布或未记录的允许列表，可以使用 `NOT_FOUND`。如果是针对用户类内某些用户的请求被拒绝，例如基于用户的访问控制，应该使用 `PERMISSION_DENIED`。
ALREADY_EXISTS	6	客户端尝试创建的实体（例如，文件或目录）已存在。
PERMISSION_DENIED	7	调用方没有执行指定操作的权限。如果由于资源耗尽（例如配额限制）而拒绝请求，应使用 `RESOURCE_EXHAUSTED`，如果调用方无法被识别，应使用 `UNAUTHENTICATED`。此错误码并不意味着请求有效或请求的实体存在或满足其他前提条件。
RESOURCE_EXHAUSTED	8	某些资源已经耗尽，可能是每用户配额，或整个文件系统已满。
FAILED_PRECONDITION	9	操作被拒绝，因为系统不在执行操作所需的状态。例如，删除的目录不为空，`rmdir` 操作应用于非目录等。服务实现者可以使用以下指导原则来决定使用 `FAILED_PRECONDITION`、`ABORTED` 或 `UNAVAILABLE`： (a) 如果客户端可以仅重试失败的调用，则使用 `UNAVAILABLE`。(b) 如果客户端应在更高层次重试（例如，当客户端指定的测试和设置失败，表示客户端应重新启动读修改写序列），则使用 `ABORTED`。(c) 如果客户端不应重试，直到系统状态明确修复，则使用 `FAILED_PRECONDITION`。例如，如果 `rmdir` 因目录不为空而失败，则应返回 `FAILED_PRECONDITION`，因为客户端应在目录中的文件被删除之前不要重试。
ABORTED	10	操作已被中止，通常是由于并发问题，如序列检查失败或事务中止。参见上面决定 `FAILED_PRECONDITION`、`ABORTED` 和 `UNAVAILABLE` 的指导原则。
OUT_OF_RANGE	11	操作尝试超出了有效范围。例如，尝试在文件结束后进行寻址或读取。与 `INVALID_ARGUMENT` 不同，这个错误表示如果系统状态发生变化，问题可以被修复。例如，一个 32 位的文件系统如果请求读取一个不在 `[0, 2^32-1]` 范围内的偏移量，将生成 `INVALID_ARGUMENT` 错误，但如果请求从文件结束后的偏移量进行读取，则会生成 `OUT_OF_RANGE` 错误。`FAILED_PRECONDITION` 和 `OUT_OF_RANGE` 之间存在一些重叠。我们建议在适用时使用 `OUT_OF_RANGE`（更具体的错误），以便迭代空间的调用方可以更容易地通过 `OUT_OF_RANGE` 错误来检测何时完成。
UNIMPLEMENTED	12	操作未实现或在此服务中不支持/启用。
INTERNAL	13	内部错误。这意味着底层系统的某些不变量被破坏。此错误码保留用于严重错误。
UNAVAILABLE	14	服务当前不可用。这通常是暂时性的问题，可以通过带有回退的重试进行修正。注意：并非所有非幂等操作都可以安全重试。
DATA_LOSS	15	无法恢复的数据丢失或损坏。
UNAUTHENTICATED	16	请求没有有效的身份验证凭据来执行该操作。

不是错误，表示操作成功。

CANCELLED

操作已被取消，通常是由调用方取消的。

UNKNOWN

未知错误。例如，如果从另一个地址空间接收到的状态值属于一个在当前地址空间未知的错误空间，可能会返回此错误。也可能是 API 返回的错误信息不足时转换为此错误。

INVALID_ARGUMENT

客户端指定了一个无效的参数。请注意，这与 FAILED_PRECONDITION 不同。INVALID_ARGUMENT 指的是不论系统状态如何，都存在问题的参数（例如，文件名格式错误）。

DEADLINE_EXCEEDED

操作在完成之前超出了截止时间。对于会改变系统状态的操作，即使操作成功完成，也可能返回此错误。例如，服务器的成功响应可能已经延迟到超出截止时间。

NOT_FOUND

请求的实体（例如，文件或目录）未找到。注意：如果整个用户类的请求被拒绝，例如渐进式功能发布或未记录的允许列表，可以使用 NOT_FOUND。如果是针对用户类内某些用户的请求被拒绝，例如基于用户的访问控制，应该使用 PERMISSION_DENIED。

ALREADY_EXISTS

客户端尝试创建的实体（例如，文件或目录）已存在。

PERMISSION_DENIED

调用方没有执行指定操作的权限。如果由于资源耗尽（例如配额限制）而拒绝请求，应使用 RESOURCE_EXHAUSTED，如果调用方无法被识别，应使用 UNAUTHENTICATED。此错误码并不意味着请求有效或请求的实体存在或满足其他前提条件。

RESOURCE_EXHAUSTED

某些资源已经耗尽，可能是每用户配额，或整个文件系统已满。

FAILED_PRECONDITION

操作被拒绝，因为系统不在执行操作所需的状态。例如，删除的目录不为空，rmdir 操作应用于非目录等。服务实现者可以使用以下指导原则来决定使用 FAILED_PRECONDITION、ABORTED 或 UNAVAILABLE： (a) 如果客户端可以仅重试失败的调用，则使用 UNAVAILABLE。(b) 如果客户端应在更高层次重试（例如，当客户端指定的测试和设置失败，表示客户端应重新启动读修改写序列），则使用 ABORTED。(c) 如果客户端不应重试，直到系统状态明确修复，则使用 FAILED_PRECONDITION。例如，如果 rmdir 因目录不为空而失败，则应返回 FAILED_PRECONDITION，因为客户端应在目录中的文件被删除之前不要重试。

ABORTED

操作已被中止，通常是由于并发问题，如序列检查失败或事务中止。参见上面决定 FAILED_PRECONDITION、ABORTED 和 UNAVAILABLE 的指导原则。

OUT_OF_RANGE

操作尝试超出了有效范围。例如，尝试在文件结束后进行寻址或读取。与 INVALID_ARGUMENT 不同，这个错误表示如果系统状态发生变化，问题可以被修复。例如，一个 32 位的文件系统如果请求读取一个不在 [0, 2^32-1] 范围内的偏移量，将生成 INVALID_ARGUMENT 错误，但如果请求从文件结束后的偏移量进行读取，则会生成 OUT_OF_RANGE 错误。FAILED_PRECONDITION 和 OUT_OF_RANGE 之间存在一些重叠。我们建议在适用时使用 OUT_OF_RANGE（更具体的错误），以便迭代空间的调用方可以更容易地通过 OUT_OF_RANGE 错误来检测何时完成。

UNIMPLEMENTED

操作未实现或在此服务中不支持/启用。

INTERNAL

内部错误。这意味着底层系统的某些不变量被破坏。此错误码保留用于严重错误。

UNAVAILABLE

服务当前不可用。这通常是暂时性的问题，可以通过带有回退的重试进行修正。注意：并非所有非幂等操作都可以安全重试。

DATA_LOSS

无法恢复的数据丢失或损坏。

UNAUTHENTICATED

请求没有有效的身份验证凭据来执行该操作。