状态码
解释 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）。如果无法识别调用者，则不得使用 PERMISSION_DENIED（对于这些错误，请改用 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 不同，此错误表明如果系统状态发生更改，则可能会修复问题。例如，如果要求读取的偏移量不在 [0, 2^32-1] 范围内，则 32 位文件系统将生成 INVALID_ARGUMENT，但如果要求从超出当前文件大小的偏移量读取，则会生成 OUT_OF_RANGE。 FAILED_PRECONDITION 和 OUT_OF_RANGE 之间存在相当大的重叠。我们建议在适用时使用 OUT_OF_RANGE（更具体的错误），以便迭代空间的调用者可以轻松查找 OUT_OF_RANGE 错误来检测何时完成。 |
| 未实现 | 12 | 此操作未实现或在此服务中不受支持/未启用。 |
| 内部错误 | 13 | 内部错误。这意味着底层系统预期的一些不变量已被破坏。此错误代码保留给严重错误。 |
| 不可用 | 14 | 该服务目前不可用。这很可能是一个瞬态情况，可以通过退避重试来纠正。请注意，重试非幂等操作并非总是安全的。 |
| DATA_LOSS | 15 | 无法恢复的数据丢失或损坏。 |
| 未认证 | 16 | 该请求不具有操作的有效身份验证凭据。 |
上次修改时间：2024 年 8 月 21 日：status-codes.md 中 DEADLINE_EXCEEDED 描述的完整句子（#1348）(081383d)