如何读懂 liteserver 错误

liteserver 对每个查询要么返回所请求的对象，要么返回一个携带整数 code 和 message 的 liteServer.error。TONNode 网关对自己的拒绝也使用同样的封装，所以你的库会像展示任何节点错误一样展示它们：tonutils-go 把错误码保存在 ton.LSError 中，pytoniq 抛出带 .code 和 .message 的 LiteServerError，而 ton-lite-client 抛出的 Error 只有文本。

错误码来自两个地方，表格会标明是哪一个：

  • 网关错误码——400、403、429、500、502——由位于你的 ADNL 连接与节点之间的 TONNode 网关产生。它根据套餐检查方法、应用速率限制和并发上限，并把查询路由到轻节点或归档节点。这些行复述了 LiteServers 文档第 5 章。
  • 节点错误码来自 ton-blockchain/ton 中的节点软件。-400 是 LiteQuery 失败文本的默认错误码，-503 timeout 是节点自己的单次查询截止时间，651 和 652 则是 common/errorcode.h 中的 ErrorCode::notready 和 ErrorCode::timeout。有两行是由 C++ 客户端本身（lite-client、tonlib）而非服务器产生的；其他语言在相同情况下会抛出各自的异常。

最重要的几个

403 archive history is not included in this plan。 遍历历史时唯一重要的信号。查询需要一个轻节点已不再保存的区块——轻节点按当前出块速度保留约两天的历史，这是数量级而非承诺——而套餐不含归档范围。它不可重试：要么为套餐添加归档，要么请求更新的区块。第 4 章解释了边界在哪里，并提供了一个为你的密钥测量边界的探测脚本。

429，三种不同的限制。 too many requests 是按密钥的速率限制，一个以成本单位计量的漏桶：一次普通读取为 5，一整页 getTransactions 最多 16，一个完整区块为 50。too many concurrent requests for this key 是在途上限——套餐 RPS 的一半，最低 8，最高 128。gateway is saturated 是所有客户共享的 256 个在途查询的全局上限。前两个意味着客户端需要控制节奏；最后一个意味着后端吃紧，正确的应对是退避。第 7 章有成本表和控制节奏的客户端代码片段。

502 backend node timeout。 节点没有在网关的时间窗口内应答：轻节点 7 秒，归档 20 秒。把你自己的客户端超时设置得高于这些数值；更短的超时会把真正的 502 变成本地超时，并丢失诊断信息。

651 与“not in db”家族。 block … is not applied、block … is not in db 和 lt not in db 都携带 ErrorCode::notready。它们表示这个节点没有准备好你所请求的内容：它仍在追赶，区块超前于它的状态，或者区块或逻辑时间比它的存储更旧。新区块会自行出现；旧区块需要归档。

什么该重试

429 退避后重试，502 立即重试一次。不要重试 403——两种变体在第二次尝试时都不会变为成功。也不要重试交易遍历返回的 -400；那是边界，不是偶发故障。对于 651，比节点状态更新的区块稍后重试，比它的存储更旧的区块则停止重试。

内存池流的错误

内存池流是另一种协议，有自己的错误列表——JSON error 消息和诸如 4401、4429 的 WebSocket 关闭码——不在本表的覆盖范围内。