状态码
解释 gRPC 中使用的状态码。
状态码
解释 gRPC 中使用的状态码。
概述
所有 RPC 都会向客户端返回一个 status。一个 status 对象由一个整数代码和一个字符串错误描述组成。服务器端（或 gRPC 库在库级别错误时）选择为给定 RPC 返回的状态。应用程序应只使用下面定义的值。
当出现错误情况时，gRPC 库可能会生成相应的 status。库可以在客户端或服务器端执行此操作。gRPC 库只生成预定义状态码的一个子集。这使得应用程序可以确信它看到的任何其他代码都是由应用程序实际返回的（尽管服务器端也可能返回由 gRPC 库生成的代码之一）。
请参阅错误处理用户指南，了解如何使用状态码。
状态码完整列表
gRPC 使用一组定义良好的状态码作为 RPC API 的一部分。
以下状态码永远不会由库生成，只由用户代码生成
- INVALID_ARGUMENT
- NOT_FOUND
- ALREADY_EXISTS
- FAILED_PRECONDITION
- ABORTED
- OUT_OF_RANGE
- DATA_LOSS
状态码完整列表
| 代码 | ID | 描述 |
|---|---|---|
| OK | 0 | 不是错误；成功时返回。 |
| CANCELLED | 1 | 操作已取消，通常由调用方取消。 |
| UNKNOWN | 2 | 未知错误。例如，当从另一个地址空间接收到的 Status 值属于此地址空间中未知的错误空间时，可能会返回此错误。此外，API 未返回足够错误信息时引发的错误也可能转换为此错误。 |
| INVALID_ARGUMENT | 3 | 客户端指定了无效参数。请注意，这与 FAILED_PRECONDITION 不同。INVALID_ARGUMENT 表示无论系统状态如何都存在问题的参数（例如，格式错误的文件名）。 |
| DEADLINE_EXCEEDED | 4 | 操作未能在截止日期前完成，截止日期已过。对于改变系统状态的操作，即使操作已成功完成，也可能返回此错误。例如，服务器的成功响应可能因延迟过长而导致截止日期已过。 |
| NOT_FOUND | 5 | 请求的某些实体（例如，文件或目录）未找到。给服务器开发者的提示：如果请求被拒绝，并且是针对一整类用户（例如，分阶段功能发布或未记录的允许列表），则可以使用 NOT_FOUND。如果请求被拒绝，并且是针对某类用户中的部分用户（例如，基于用户的访问控制），则必须使用 PERMISSION_DENIED。 |
| ALREADY_EXISTS | 6 | 客户端尝试创建的实体（例如，文件或目录）已存在。 |
| PERMISSION_DENIED | 7 | 调用方没有执行指定操作的权限。PERMISSION_DENIED 不得用于因资源耗尽而导致的拒绝（对于此类错误，应使用 RESOURCE_EXHAUSTED）。如果无法识别调用方（对于此类错误，应使用 UNAUTHENTICATED），则不得使用 PERMISSION_DENIED。此错误代码不意味着请求有效、请求的实体存在或满足其他前置条件。 |
| RESOURCE_EXHAUSTED | 8 | 某些资源已耗尽，可能是每用户配额，也可能是整个文件系统空间不足。 |
| FAILED_PRECONDITION | 9 | 操作被拒绝，因为系统不处于执行该操作所需的状态。例如，要删除的目录非空，对非目录执行 rmdir 操作等。服务实现者可以使用以下指导原则来区分 FAILED_PRECONDITION、ABORTED 和 UNAVAILABLE： (a) 如果客户端可以仅重试失败的调用，则使用 UNAVAILABLE。(b) 如果客户端应在更高级别重试（例如，当客户端指定的 test-and-set 失败时，表明客户端应重新开始读-修改-写序列），则使用 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 | 该请求没有针对此操作的有效认证凭据。 |
最后修改于 2024 年 8 月 21 日：完善 status-codes.md 中 DEADLINE_EXCEEDED 的描述句 (#1348) (081383d)