本页介绍了 Spanner 错误代码以及处理这些错误的建议操作。Google API（包括 Spanner）使用 google.rpc.Code 定义的规范错误代码。
当 Spanner 请求成功时，API 将返回一个 HTTP 200 OK 状态代码，并在响应正文中随附请求的数据。
请求失败时，Spanner API 会返回 HTTP 4xx 或 5xx 状态代码，一般用来标识失败，另外还会返回一项响应，用于提供有关导致失败的错误的更具体信息。
响应对象包含单个字段 error，其值包含以下元素：
| 元素 | 说明 |
|---|---|
code |
HTTP 状态代码，一般用于标识请求失败。 |
message |
有关请求失败的具体信息。 |
status |
Google API 的规范错误代码 (google.rpc.Code)。如需了解 Spanner API 可能返回的代码，请参阅错误代码。 |
如果采用 application/x-protobuf 内容类型发出的请求导致错误，则将返回一个序列化的 google.rpc.Status 消息作为载荷。
错误代码
如需对错误进行分类，推荐的方式是检查规范错误代码 (google.rpc.Code) 的值。在 JSON 错误中，此代码出现在 status 字段中。在 application/x-protobuf 错误中，此代码出现在 code 字段中。
| 错误代码 | 说明 | 建议采取的操作 |
|---|---|---|
ABORTED |
操作已中止，通常是由于序列器检查失败或事务中止等并发问题。表示该请求与另一请求发生冲突。 | 对于非事务性提交： 重试该请求或设计实体结构以减少争用。 对于随事务性提交而发出的请求： 重试整个事务或设计实体结构以减少争用。 |
ALREADY_EXISTS |
客户端尝试创建的实体已存在（例如，插入具有现有主键的行）。 | 在解决问题之前，请勿重试。 |
CANCELLED |
操作已取消（通常是被调用者取消）。 | 重试该操作。 |
DEADLINE_EXCEEDED |
期限已到，但操作尚未完成。 | 调查截止期限是否足够。使用与实际有用回复时间相符的截止期限。请注意，对于更改系统状态的操作，即使操作已成功完成，也可能会返回错误。 如需获取提示，请参阅排查截止期限已过错误。 |
FAILED_PRECONDITION |
操作被拒绝，因为未满足请求的先决条件。错误响应中的消息字段提供了未满足的先决条件的相关信息。例如，从超出时间戳过时上限的时间戳读取或查询。 | 在解决问题之前，请勿重试。 |
INTERNAL |
服务器返回了一个错误。底层系统所期望的一些不变量已损坏。 | 除非您了解错误的具体情况和原因，否则请勿重试。 |
INVALID_ARGUMENT |
客户端指定的值无效。错误响应中的消息字段提供了无效值的相关信息。 | 在解决问题之前，请勿重试。 |
NOT_FOUND |
表示某个请求的实体（例如更新实体或查询表或列）不存在。 | 在解决问题之前，请勿重试。 |
OUT_OF_RANGE |
尝试执行的操作已超出有效范围。 | 在解决问题之前，请勿重试。 |
PERMISSION_DENIED |
用户无权发出该请求。 | 在解决问题之前，请勿重试。 |
RESOURCE_EXHAUSTED |
部分资源已用尽。 对于管理控制平面，可能是项目超出了其配额，或者整个文件系统的存储空间已用尽。 对于数据平面，如果 Spanner 节点过载，就可能会发生这种情况。 |
对于管理控制平面，请验证您是否超出了 Spanner 或项目配额。如果您超出了配额，请申请增加配额或等待配额重置，然后再重试。将重试配置为使用指数退避算法。 对于数据平面，请验证您的 Spanner 节点是否未超出其容量。Spanner 会在客户端库中重试这些错误。如果所有重试都失败，请参阅流控制机制错误。 一般来说，如果您的应用出现 RESOURCE_EXHAUSTED 错误，请将此情况视为 UNAVAILABLE 错误，并使用指数退避算法重试。 |
UNAUTHENTICATED |
请求没有相应操作的有效身份验证凭据。 | 在解决问题之前，请勿重试。 |
UNAVAILABLE |
服务器不可用。 | 使用指数退避算法重试。请注意，重试执行非幂等操作并非总是安全的。 |
UNIMPLEMENTED |
操作在此服务中未实现或不受支持/未启用。 | 在解决问题之前，请勿重试。 |
UNKNOWN |
服务器返回了未知错误。因 API 没有返回足够错误信息而引发的错误也可能会转换为此错误。 | 检查您的请求是否安全。然后，使用指数退避算法重试。 |
流控制机制错误
在以下情况下，Spanner 可能会启用其流量控制机制，以保护自己免受过载：
- Spanner 节点的 CPU 使用率较高。如果您怀疑请求导致 CPU 使用率过高，可以使用 CPU 利用率指标来调查问题。
- 可能存在热点，这会增加请求的处理时间。如果您怀疑自己的请求会导致热点，请参阅在数据库中查找热点以调查问题。如需了解详情，请参阅 Key Visualizer。
以下客户端库支持流控制机制：
由于使用了流控制机制，请求完成的总时间不会增加。如果没有此机制，Spanner 会先等待，然后再处理请求，并最终返回 DEADLINE_EXCEEDED 错误。
当流量控制机制处于活跃状态时，Spanner 会将请求推送回客户端以进行重试。如果重试耗尽了用户提供的整个截止期限，则客户端会收到 RESOURCE_EXHAUSTED 错误。如果 Spanner 估计请求的处理时间过长，则会返回此错误。该错误会传播流控制，Spanner 会向客户端重试请求，而不是在内部累积重试次数。这样，Spanner 便可避免累积额外的资源消耗。