Code

gRPC API 的规范错误代码。

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

枚举
OK

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

HTTP 映射:200 OK

CANCELLED

操作已取消(通常是被调用者取消)。

HTTP 映射:499 Client Closed Request

UNKNOWN

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

HTTP 映射:500 Internal Server Error

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_PRECONDITIONABORTED 还是 UNAVAILABLE:(a) 如果客户端只能重试失败的调用,则使用 UNAVAILABLE。(b) 如果客户端应在较高级别重试,请使用 ABORTED。例如,当客户端指定的测试和设置失败时,就表示客户端应重启读取-修改-写入序列。(c) 如果客户端不得在系统状态明确修正前执行重试,则使用 FAILED_PRECONDITION。例如,如果因非空目录而导致“rmdir”失败,则应返回 FAILED_PRECONDITION,因为客户端不应重试,除非文件已从目录中删除。

HTTP 映射:400 Bad Request

ABORTED

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

请参阅上述准则以确定是选择 FAILED_PRECONDITIONABORTED 还是 UNAVAILABLE

HTTP 映射:409 Conflict

OUT_OF_RANGE

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

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

FAILED_PRECONDITIONOUT_OF_RANGE 之间有一定的重叠。我们建议在适用时使用 OUT_OF_RANGE(更具体的错误),以便迭代空间的调用方可以轻松地查找 OUT_OF_RANGE 错误来检测完成的时间。

HTTP 映射:400 Bad Request

UNIMPLEMENTED

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

HTTP 映射:501 Not Implemented

INTERNAL

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

HTTP 映射:500 Internal Server Error

UNAVAILABLE

该服务目前不可用。这很可能是一种暂时情况,可以通过退避重试来纠正。 请注意,重试执行非幂等操作并非总是安全的。

请参阅上述准则以确定是选择 FAILED_PRECONDITIONABORTED 还是 UNAVAILABLE

HTTP 映射:503 Service Unavailable

DATA_LOSS

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

HTTP 映射:500 Internal Server Error