Package google.rpc

索引

代码

gRPC API 的规范错误代码。

有时可能有多个错误代码都适用。服务应返回适用且最具体的错误代码。例如，如果 OUT_OF_RANGE 和 FAILED_PRECONDITION 两个代码都适用，则前者优先于后者。同样，NOT_FOUND 或 ALREADY_EXISTS 优先于 FAILED_PRECONDITION。

枚举
OK

不是错误信息；成功时返回此项

HTTP 映射：200 OK
CANCELLED

操作已取消（通常是被调用者取消）。

HTTP 映射：499 Client Closed Request
UNKNOWN

未知错误。例如，当从另一个地址空间接收到的 Status 值属于此地址空间中未知的错误空间时，可能返回此错误。另外，因 API 没有返回足够错误信息而引发的错误也可能会转换为此错误。

HTTP 映射：500 内部服务器错误
INVALID_ARGUMENT

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

HTTP 映射：400 Bad Request
DEADLINE_EXCEEDED

在操作完成之前截止期限已过。对于更改系统状态的操作，即使操作已成功完成，也可能会返回此错误。例如，服务器的成功响应可能会延迟足够长的时间以使截止期限过期。

HTTP 映射：504 Gateway Timeout
NOT_FOUND

找不到所请求的部分实体（例如，文件或目录）。

服务器开发者注意：如果要拒绝整个一类用户的请求（例如，功能逐步发布的用户或未正式加入许可名单的用户），则可以使用 NOT_FOUND。如果要拒绝某一类用户中部分用户的请求（例如，基于用户的访问权限控制），则必须使用 PERMISSION_DENIED。

HTTP 映射：404 Not Found
ALREADY_EXISTS

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

HTTP 映射：409 Conflict
PERMISSION_DENIED

调用者无权执行指定的操作。如果遭拒的原因是由于部分资源已用尽，则不得使用 PERMISSION_DENIED（请改用 RESOURCE_EXHAUSTED 来表示此类错误）。如果调用者无法识别，则不得使用 PERMISSION_DENIED（请改用 UNAUTHENTICATED 来表示此类错误）。此错误代码并不意味着请求有效，或者请求的实体存在或满足其他先决条件。

HTTP 映射：403 Forbidden
UNAUTHENTICATED

请求没有相应操作的有效身份验证凭据。

HTTP 映射：401 Unauthorized
RESOURCE_EXHAUSTED

部分资源已用尽，可能是每用户配额不足，也可能是整个文件系统的存储空间已用完。

HTTP 映射：429 Too Many Requests
FAILED_PRECONDITION

操作被拒绝，因为系统未处于执行该操作所需的状态。例如，要删除的目录非空、将 rmdir 操作应用于非目录等等。

服务实施者可根据以下准则来确定是选择 FAILED_PRECONDITION、ABORTED 还是 UNAVAILABLE：(a) 如果客户端只能重试失败的调用，则使用 UNAVAILABLE。(b) 如果客户端应在更高级层执行重试，则使用 ABORTED（例如当客户端指定的“测试并设置”操作失败时，这意味着客户端应重启“读取-修改-写入”序列）。(c) 如果客户端不得在系统状态明确修正前执行重试，则使用 FAILED_PRECONDITION。例如，如果因非空目录而导致“rmdir”失败，应返回 FAILED_PRECONDITION，因为客户端只能在目录中的文件删除之后执行重试。

HTTP 映射：400 Bad Request
ABORTED

操作已中止，通常是由于序列程序检查失败或事务中止等并发问题。

请参阅上述准则以确定是选择 FAILED_PRECONDITION、ABORTED 还是 UNAVAILABLE。

HTTP 映射：409 Conflict
OUT_OF_RANGE

尝试执行的操作已超出有效范围。例如，查找或读取操作已超出文件末尾。

与 INVALID_ARGUMENT 不同，此错误指示的问题可以通过改变系统状态得到修复。例如，如果要求的读取操作偏移量不在 [0,2^32-1] 范围内，则 32 位文件系统将会生成 INVALID_ARGUMENT，但如果要求的读取操作偏移量超过当前文件大小，该系统则会生成 OUT_OF_RANGE。

FAILED_PRECONDITION 和 OUT_OF_RANGE 之间有一定的共通之处。我们建议尽量使用 OUT_OF_RANGE（错误更具体一些），这样，循环访问空间的调用者就可以轻松查找 OUT_OF_RANGE 错误以检测完成情况。

HTTP 映射：400 Bad Request
UNIMPLEMENTED

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

HTTP 映射：501 Not Implemented
INTERNAL

内部错误。这意味着底层系统所期望的一些不变量已损坏。此错误代码保留用于严重错误。

HTTP 映射：500 内部服务器错误
UNAVAILABLE

该服务目前不可用。这很可能是一种暂时情况，可以通过退避重试来纠正。

请参阅上述准则以确定是选择 FAILED_PRECONDITION、ABORTED 还是 UNAVAILABLE。

HTTP 映射：503 Service Unavailable
DATA_LOSS

数据丢失或损坏且不可恢复。

HTTP 映射：500 内部服务器错误

状态

Status 类型定义了适用于不同编程环境（包括 REST API 和 RPC API）的逻辑错误模型。此类型供 gRPC 使用。设计错误模型的目的是：

  • 方便大多数用户使用和理解
  • 足够灵活地应对意外需求

概览

Status 消息包含三项数据：错误代码、错误消息和错误详细信息。错误代码应为 google.rpc.Code 的枚举值，但如果需要，也可以接受其他错误代码。错误消息应为向开发者显示的英语版消息，旨在帮助开发者理解并解决相关错误。如果需要提供向用户显示的本地化版错误消息，可以将本地化后的消息放入错误详细信息中，也可以在客户端中将该消息本地化。错误详细信息是可选项，其中可包含错误的任意相关信息。google.rpc 软件包中包含一组预定义的错误详细信息类型，可用于常见的错误情况。

语言映射

Status 消息是错误模型的逻辑表示形式，但不一定是实际的传输格式。当 Status 消息在不同的客户端库和不同的传输协议中公开时，可以采用不同的方式映射。例如，此消息可能映射到 Java 中的某些异常，但更可能映射到 C 中的某些错误代码。

其他用途

错误模型和 Status 消息可用于各种环境（无论是否使用 API），以便在不同环境中提供一致的开发者体验。

下面是此错误模型的一些示例运用：

  • 部分错误。如果服务需要将部分错误返回到客户端，则可以将 Status 嵌入正常响应中，以指示部分错误。

  • 工作流错误。一个典型的工作流包含多个步骤。每个步骤都有一条用于报告错误的 Status 消息。

  • 批量操作。如果客户端使用批量请求和批量响应，则应直接在批量响应中使用 Status 消息，使每个错误子响应与一条消息对应。

  • 异步操作。如果 API 调用将异步操作结果嵌入其响应中，则应直接使用 Status 消息表示这些操作的状态。

  • 日志记录。如果某些 API 错误存储在日志中，则在为确保安全/隐私而执行任何必要的删除操作之后，可以直接使用 Status 消息。

字段
code

int32

状态代码，应是 google.rpc.Code 的枚举值。

message

string

面向开发者的错误消息（应采用英语）。任何向用户显示的错误消息都应进行本地化并通过 google.rpc.Status.details 字段发送，或者由客户端进行本地化。
details[]

Any

包含错误详细信息的消息列表。有一组通用的消息类型可供 API 使用。