状态码
解释 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)