Package google.rpc

索引

BadRequest

描述客户端请求中的违规行为。此类错误侧重于请求的语法方面。

字段
field_violations[]

FieldViolation

描述客户端请求中的所有违规行为。

FieldViolation

用于描述单个错误请求字段的消息类型。

字段
field

string

指向请求正文中字段的路径。此值是一个以点分隔的标识符序列，用于标识协议缓冲区字段。

请考虑以下事项：

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

在此示例中，在 proto 中，field 可以采用以下值之一：

  • full_name，用于 full_name 值中的违规情况
  • email_addresses[1].email 表示第一个 email_addresses 消息的 email 字段中存在违规行为
  • email_addresses[3].type[2]，表示第三条消息中第二个 email_addresses 值的第二个 type 值存在违规情况。

在 JSON 中，相同的值表示为：

  • fullName，用于 fullName 值中的违规情况
  • emailAddresses[1].email 表示第一个 emailAddresses 消息的 email 字段中存在违规行为
  • emailAddresses[3].type[2]，表示第三条消息中第二个 emailAddresses 值的第二个 type 值存在违规情况。
description

string

对请求元素存在问题的原因的说明。
reason

string

字段级错误的原因。这是一个常量值，用于标识字段级错误的近因。它应在 google.rpc.ErrorInfo.domain 的范围内唯一标识 FieldViolation 的类型。此值不得超过 63 个字符，并且必须与正则表达式 [A-Z][A-Z0-9_]+[A-Z0-9]（表示 UPPER_SNAKE_CASE）匹配。
localized_message

LocalizedMessage

针对字段级错误提供本地化错误消息，可安全地返回给 API 使用者。

代码

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 内部服务器错误

错误信息

使用结构化详细信息描述错误的原因。

未启用“pubsub.googleapis.com”API 时，联系该 API 时出现的错误示例：

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

此响应表明 pubsub.googleapis.com API 未启用。

尝试在缺货的区域中创建 Spanner 实例时返回的错误示例：

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
字段
reason

string

错误的原因。这是一个常量值，用于标识错误的直接原因。错误原因在特定错误网域内是唯一的。此值不得超过 63 个字符，并且必须与正则表达式 [A-Z][A-Z0-9_]+[A-Z0-9]（表示 UPPER_SNAKE_CASE）匹配。
domain

string

“原因”所属的逻辑分组。错误网域通常是生成错误的工具或产品的注册服务名称。示例：“pubsub.googleapis.com”。如果错误是由某些常见的基础设施生成的，则错误网域必须是标识该基础设施的全局唯一值。对于 Google API 基础架构，错误网域为“googleapis.com”。
metadata

map<string, string>

有关此错误的其他结构化详细信息。

键必须与正则表达式 [a-z][a-zA-Z0-9-_]+ 匹配，但最好采用 lowerCamelCase 格式。此外，长度不得超过 64 个字符。在确定超出限值的当前值时，单位应包含在键中，而不是值中。例如，如果客户端在单个（批量）请求中创建的实例数量超出上限，则应返回 {"instanceLimitPerRequest": "100"}，而不是 {"instanceLimit": "100/request"}。

帮助

提供指向文档的链接或用于执行带外操作的链接。

例如，如果配额检查失败并显示错误，指出调用项目尚未启用所访问的服务，则此对象可能包含一个网址，该网址直接指向开发者控制台中用于切换相应位的位置。

字段

LocalizedMessage

提供可安全返回给用户的本地化错误消息，该消息可附加到 RPC 错误。

字段
locale

string

所用语言区域遵循 https://www.rfc-editor.org/rfc/bcp/bcp47.txt 中定义的规范。例如：“en-US”“fr-CH”“es-MX”
message

string

上述语言区域中的本地化错误消息。

PreconditionFailure

描述哪些前提条件未能满足。

例如，如果 RPC 因需要确认服务条款而失败，则可能会在 PreconditionFailure 消息中列出违反服务条款的情况。

字段
violations[]

Violation

描述所有前提条件违规情况。

违规

用于描述单个前提条件失败的消息类型。

字段
type

string

PreconditionFailure 的类型。我们建议使用特定于服务的枚举类型来定义支持的前提条件违规主题。例如，“TOS”表示“违反《服务条款》”。
subject

string

失败的主题（相对于类型）。例如，相对于“TOS”类型的“google.com/cloud”表示所引用的服务条款。
description

string

有关前提条件失败原因的说明。开发者可以根据此说明了解如何修复故障。

例如：“尚未接受服务条款”。

QuotaFailure

描述配额检查失败的方式。

例如，如果调用项目的每日限额被超出，服务可能会返回一个 QuotaFailure 详情，其中包含项目 ID 和超出限额的说明。如果调用项目尚未在开发者控制台中启用该服务，则服务可能会以项目 ID 进行响应，并将 service_disabled 设置为 true。

另请参阅 RetryInfo 和 Help 类型，了解有关处理配额失败的其他详细信息。

字段
violations[]

Violation

描述所有配额违规情况。

违规

用于描述单个配额违规情况的消息类型。例如，超出每日配额或自定义配额。

字段
subject

string

配额检查失败的主题。例如，“clientip:”或“project:”。
description

string

配额检查失败方式的说明。客户端可以使用此说明在服务的公开文档中详细了解配额配置，或通过开发者控制台找到相关配额限制进行调整。

例如：“服务已停用”或“超出读取操作的每日限额”。
api_service

string

QuotaFailure.Violation 的来源 API 服务。在某些情况下，配额问题源于被调用的 API 服务以外的其他 API 服务。换句话说，被调用的 API 服务的依赖项可能是 QuotaFailure 的原因，而此字段将包含依赖项 API 服务名称。

例如，如果调用的 API 是 Kubernetes Engine API (container.googleapis.com)，并且 Kubernetes Engine API 本身发生了配额违规，则此字段将为“container.googleapis.com”。另一方面，如果 Kubernetes Engine API 在 Compute Engine API (compute.googleapis.com) 中创建虚拟机时发生配额违规，则此字段将为“compute.googleapis.com”。
quota_metric

string

违规配额的指标。配额指标是用于衡量用量（例如 API 请求或 CPU）的命名计数器。当服务中发生某项活动（例如虚拟机分配）时，一个或多个配额指标可能会受到影响。

例如，“compute.googleapis.com/cpus_per_vm_family”“storage.googleapis.com/internet_egress_bandwidth”。
quota_id

string

违规配额的 ID。也称为“限额名称”，是 API 服务上下文中配额的唯一标识符。

例如，“CPUS-PER-VM-FAMILY-per-project-region”。
quota_dimensions

map<string, string>

违反的配额的维度。所有非全局配额都会根据一组维度来强制执行。配额指标定义了要统计的内容，而维度则指定了应针对哪些方面增加计数器。

例如，“每个区域每个虚拟机系列的 CPU 数”配额会针对“region”和“vm_family”维度对“compute.googleapis.com/cpus_per_vm_family”指标强制执行限制。如果违规行为发生在“us-central1”区域，并且针对的是“n1”虚拟机系列，则 quota_dimensions 将为：

{ "region": "us-central1", "vm_family": "n1", }

如果配额是在全球范围内强制执行的，则 quota_dimensions 始终为空。
quota_value

int64

QuotaFailure 时强制执行的配额值。

例如，如果 QuotaFailure 时强制执行的 CPU 数量配额值为“10”，则此字段的值将反映此数量。
future_quota_value

int64

违规时正在推出的新配额值。发布完成后，系统将强制执行此值，而不是 quota_value。如果违规时没有正在进行的发布，则不会设置此字段。

例如，如果违规时正在进行一项发布，将 CPU 配额从 10 更改为 20，则此字段的值为 20。

RequestInfo

包含有关客户端在提交 bug 或提供其他形式的反馈时可以附加的请求的元数据。

字段
request_id

string

一个不透明的字符串，应仅由生成它的服务进行解释。例如，它可以用于识别服务日志中的请求。
serving_data

string

用于处理相应请求的所有数据。例如，可以发送回服务提供商以进行调试的加密堆栈轨迹。

ResourceInfo

描述正在访问的资源。

字段
resource_type

string

所访问资源类型的名称，例如“SQL 表”“Cloud Storage 存储分区”“文件”“Google 日历”；或资源的类型网址，例如“type.googleapis.com/google.pubsub.v1.Topic”。
resource_name

string

所访问资源的名称。例如，如果当前错误为 google.rpc.Code.PERMISSION_DENIED，则共享日历名称为“example.com_4fghdhgsrgh@group.calendar.google.com”。
owner

string

资源的所有者（可选）。例如，“user:”或“project:”。
description

string

描述访问相应资源时遇到的错误。例如，更新云项目可能需要开发者控制台项目的 writer 权限。

RetryInfo

描述客户端何时可以重试失败的请求。如果错误响应中缺少此信息，客户端可以忽略此建议或重试。

我们始终建议客户端在重试时使用指数退避算法。

客户端应等待自收到错误响应以来经过 retry_delay 时间量后，再进行重试。如果重试请求也失败，客户端应使用指数退避方案，根据 retry_delay 逐渐增加重试之间的延迟，直到达到最大重试次数或最大重试延迟上限。

字段
retry_delay

Duration

客户端在重试同一请求时，应至少等待这么长时间。

状态

Status 类型定义了适用于不同编程环境（包括 REST API 和 RPC API）的逻辑错误模型。此类型供 gRPC 使用。每条 Status 消息包含三部分数据：错误代码、错误消息和错误详细信息。

如需详细了解该错误模型及其使用方法，请参阅 API 设计指南。

字段
code

int32

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

string

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

Any

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