本页面介绍了 Spanner 错误代码以及处理这些错误的建议操作。包括 Spanner 在内的 Google API 使用 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 使用会话来管理应用与数据库之间的互动。会话表示与数据库的连接，并有助于执行读取和写入等操作。
应用可能会遇到的常见会话相关错误包括：
找不到会话
当应用尝试使用不再存在的会话时，会发生 Session not found 错误。这可能是由于多种原因造成的。
您的客户端应用可能会明确删除会话。例如，在代码中关闭数据库客户端或直接调用
deleteSessionsAPI 都会移除会话。如果您未使用任何 Spanner 客户端库，请在出现此错误时创建新会话。将新会话添加到会话池中，并从池中移除已删除的会话。在某些情况下，Spanner 还会自动删除会话。
如果会话空闲超过一小时，系统会将其删除。如果数据流作业的下游处理时间长于会话空闲超时时间，则可能会发生这种情况。如果您使用的是 Dataflow 作业，请在 Dataflow 流水线中的 Spanner 读取操作后添加
Reshuffle转换操作。这有助于将 Spanner 读取操作与后续长时间运行的处理步骤分离。如果会话存在超过 28 天，Spanner 也会删除该会话。如果您使用的是客户端库，则该库会自动处理这些情况。如果您未使用任何 Spanner 客户端库，请在出现此错误时创建新会话。将新会话添加到会话池中，并从池中移除已删除的会话。
如果您使用 Spanner 客户端库，则该库会自动管理会话。如果您遇到此错误，请验证您的代码是否未明确删除会话，例如通过关闭数据库客户端来删除会话。有时，这还可能是由客户端库的会话管理方面的问题引起的。
资源已用完
RESOURCE_EXHAUSTED: No session available in the pool 或 RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session 错误表明您的应用无法从会话池获取会话。当没有会话可用于处理新的读取或写入请求时，就会发生这种情况。
下表介绍了可能导致这些错误的一些原因，以及相应的建议措施。
| 原因 | 建议采取的操作 |
|---|---|
| 池中的所有会话都在使用中。您的应用收到的并发请求数可能超过配置的会话数上限。池中的所有会话均被占用，没有可用于新请求的会话。 |
启用多路复用会话。
借助多路复用会话，多个事务和读取操作可以共享单个会话，从而减少应用所需的会话总数。您还可以在会话池设置中增加 maxSession 或 minSession 配置。 |
| 请求需要很长时间才能完成。长时间运行的读取或写入请求可能会长时间占用所有可用会话。 如果这些请求花费的时间超过会话获取超时设置，则新请求无法从会话池中获取会话。 | 调查请求需要很长时间才能完成的原因。优化查询或应用逻辑以缩短执行时间。您可以增加会话获取超时设置。 您还可以为符合条件的客户端库启用多路复用会话，以提高会话利用率。 |
| 存在会话泄露。当应用从池中检出会话，但在完成请求后未将其返回时，就会发生会话泄漏。当您的代码中未正确关闭迭代器或结果集时，通常会发生此问题。如果所有会话都发生泄漏，则没有会话可用于新请求。 | 调试应用代码，以找出并修复会话泄漏问题。 确保您的代码正确关闭所有迭代器和结果集。 如需了解详情，请参阅会话泄露检测解决方案。 您还可以使用自动清理会话泄露功能，将您的会话池设置为自动解决不活跃的事务。 |
会话创建速度较慢。创建会话是一项计算开销很大的操作。客户端库会发送 BatchCreateSessions API 来创建初始会话（基于 minSession 配置），并发送 CreateSessions API 来创建其他会话（最多 maxSession 个）。如果创建会话的时间超过会话获取超时设置，则新请求在等待会话时可能会超时。 |
验证 BatchCreateSessions 和 CreateSessions API 调用的延迟时间。会话创建速度缓慢可能是 Spanner 端的资源问题或大量并发会话创建操作所致。 |
流控制机制错误
在以下情况下，Spanner 可能会启动其流量控制机制，以防止自身过载：
- Spanner 节点的 CPU 使用率较高。如果您怀疑请求导致 CPU 使用率过高，可以使用 CPU 利用率指标来调查问题。
- 可能存在热点，这会增加请求的处理时间。 如果您怀疑自己的请求导致了热点，请参阅查找数据库中的热点以调查问题。如需了解详情，请参阅 Key Visualizer。
以下客户端库支持流量控制机制：
使用流量控制机制不会增加请求完成的总时间。如果没有此机制，Spanner 会在处理请求之前等待，最终返回 DEADLINE_EXCEEDED 错误。
当流量控制机制处于有效状态时，Spanner 会将请求推送回客户端以进行重试。如果重试消耗了用户提供的整个截止时间，则客户端会收到 RESOURCE_EXHAUSTED 错误。如果 Spanner 估计请求的处理时间过长，则会返回此错误。错误会传播流量控制，并且 Spanner 会向客户端重试请求，而不是在内部累积重试。这样，Spanner 便可避免累积额外的资源消耗。