Skip to main content

安装问题

症状: npm install kaleido-sdk 报错失败解决办法:
  1. 确认已安装 Node.js 18+:node --version
  2. 清理 npm 缓存:npm cache clean --force
  3. 删除 node_modules 和 package-lock.json,然后重新安装
  4. 换一个包管理器试试:pnpm add kaleido-sdk
症状: pip install kaleido-sdk 失败解决办法:
  1. 确认已安装 Python 3.10+:python --version
  2. 使用虚拟环境:python -m venv .venv && source .venv/bin/activate
  3. 升级 pip:pip install --upgrade pip
  4. 试试:pip install kaleido-sdk --no-cache-dir
症状: Cannot find module 'kaleido-sdk'、ERR_REQUIRE_ESM、import 语法报错,或 ModuleNotFoundError原因(TypeScript): SDK 仅支持 ESM,而旧的 "moduleResolution": "node" 设置会忽略包的 exports 字段。解决办法:
  • TypeScript: 在 tsconfig.json 中将 "moduleResolution" 设为 "bundler"、"node16" 或 "nodenext",并让项目本身使用 ESM —— 在 package.json 中设置 "type": "module",或使用 .mts 扩展名。如果必须继续使用 CommonJS,请改用动态导入:const sdk = await import('kaleido-sdk')
  • Python: 确认你处在正确的虚拟环境中
  • 确认包已安装:npm list kaleido-sdk 或 pip show kaleido-sdk

运行时错误

症状: 调用 API 时抛出 NetworkError原因:
  • API 服务器不可达
  • baseUrl 有误
  • 防火墙拦截了请求
解决办法:
  1. 确认 baseUrl 正确且可访问
  2. 检查网络连通性
  3. 在浏览器中访问该 API URL 试试:https://api.signet.kaleidoswap.com/api/v1/market/assets
  4. 如果处在防火墙之后,确认已放行出向 HTTPS
症状: 调用 client.rln.* 方法时,TypeScript 抛出 ConfigError(“Node API not configured…”),Python 抛出 NodeNotConfiguredError原因: 创建客户端时没有提供 nodeUrl / node_url。解决办法:
调用 RLN 方法前,务必先检查 client.hasNode() / client.has_node()。
症状: 带 rfq_id 调用 initSwap / init_swap 时抛出 QuoteExpiredError原因: 报价的 expires_at 时间已经过了。解决办法:
  1. 在调用 initSwap 之前才去获取新报价 —— 不要让一个 rfq_id 跨越用户的思考时间继续使用
  2. 用 WebSocket 流式推送来保证报价始终是最新的
  3. 尽快完成白名单和执行;整个 初始化 → 白名单 → 执行 的流程都基于同一个报价
症状: 抛出 ValidationError,错误信息与金额相关原因:
  • 金额低于最小值或高于最大值
  • 精度用错了(发送的是展示单位而不是原始单位)
  • 金额为负数或零
解决办法:
  1. 从 listPairs 的响应中查看最小/最大限额
  2. 确认你发送的是原始金额而不是展示金额 —— 用工具函数中的 parseRawAmount / parse_raw_amount 进行换算
  3. 在发送之前先校验金额
症状: 抛出状态码为 401 的 APIError原因: API key 无效或缺失。解决办法:
  1. 检查 apiKey / api_key 是否设置正确
  2. 确认该密钥有效且未过期
  3. 有些接口端点可能并不需要 API key —— 请查阅客户端参考
症状: API 调用抛出 TimeoutError原因:
  • 网络连接较慢
  • 服务器负载过高
  • 超时时间设置得太短
解决办法:
  1. 增大超时时间:timeout: 60(单位为秒)
  2. 检查网络连通性
  3. 用 error.isRetryable() 实现重试逻辑 —— 参见重试模式
症状: 重复调用时抛出 RateLimitError,通常出现在轮询报价的场景中原因: 在速率限制窗口内发出了过多请求。解决办法:
  1. 先退避再重试,并遵守响应中携带的 retry_after(在 Python 中,速率限制错误的 is_retryable() 返回 False,需要你自己退避)
  2. 改用 WebSocket 流式接收报价,而不是循环轮询 getQuote
  3. 缓存 listAssets / listPairs 的结果,不要每次操作都重新拉取

交换问题

症状: initSwap 成功,但 executeSwap / execute_swap 失败并抛出 SwapError原因: initSwap 返回的 swapstring 从未在你自己的节点上加入白名单,因此接单方无法履行该 HTLC。解决办法: 这三步必须按顺序执行,而且加入白名单这一步是在 client.rln 上完成,而不是 client.maker:
  1. client.maker.initSwap(...) → 返回 swapstring
  2. client.rln.whitelistSwap(swapstring) → 你的节点接受这笔交换
  3. client.maker.executeSwap(...) → 做市方完成结算
完整流程见如何进行交换。
症状: 初始化或执行时抛出 InsufficientBalanceError原因:
  • 你要发送的这一侧在通道上的出向容量不足
  • 除交换金额之外,还需要预留的粉尘储备不可用
  • 余额在链上,而不在通道里
解决办法:
  1. 通过 client.rln.listChannels() 检查对应资产的出向容量,而不只看总余额
  2. 确认金额在 listPairs 给出的该交易对最小/最大限额之内
  3. 如果容量不够,通过 LSPS1 追加入向或出向流动性
症状: executeSwap 已经返回,但资产没有到账解决办法:
  1. 轮询 client.maker.getAtomicSwapStatus(...) / get_atomic_swap_status(...),不要以为执行就是终态
  2. 调用 client.rln.refreshTransfers() / refresh_transfers() 推进处于待处理状态的 RGB 转移
  3. 通过 client.rln.listSwaps() 查看节点自己对这笔交换的记录
症状: 某个调用在解析阶段失败(Pydantic 的 ValidationError,或者某个 TypeScript 字段意外为 undefined),而不是返回一个明确的 SDK 错误原因: SDK 与它所对接的 API 是基于不同版本的规范生成的。这种情况在节点侧最常见,因为 RLN 的版本由你自己掌控。解决办法:
  1. 把你节点的版本与你所用 SDK 版本对应的目标版本对比 —— 参见 RLN API 兼容性
  2. 升级 SDK:npm install kaleido-sdk@latest 或 pip install --upgrade kaleido-sdk
  3. 查看更新日志,了解你当前版本与最新版本之间的破坏性变更 —— 有几个版本新增了现在已成为必填的请求字段

WebSocket 问题

症状: connected 事件始终不触发,或者抛出 WebSocketError解决办法:
  1. 确认 WebSocket URL 正确(应以 wss:// 开头)
  2. 确认在开始流式接收之前调用过 enableWebSocket / enable_websocket
  3. 检查 WebSocket 连接是否被防火墙或代理拦截
  4. 在 URL 中换一个 client ID 试试
症状: quoteResponse / quote_response 事件始终不触发解决办法:
  1. 确认该资产交易对有效且存在可用路由
  2. 检查金额是否在最小/最大限额之内
  3. 监听 WSClient 上的 error 事件
  4. 确认连接已经建立(检查 connected 事件)
症状: WebSocket 反复断开并重连解决办法:
  1. 检查网络是否稳定
  2. WSClient 会以指数退避自动重连
  3. 监听 reconnecting 事件以跟踪重连尝试
  4. 如果触发了 maxReconnectExceeded,就手动重连:

语言相关问题

症状: TypeScript 编译器报告类型不兼容解决办法:
  1. 确认你是从 kaleido-sdk 导入类型:
  2. 检查 TypeScript 版本是否为 5.0+
  3. 如果启用了 strict 模式,可能需要显式处理 undefined
症状: 解析 API 响应时 Pydantic 抛出 ValidationError解决办法:
  1. 确认已安装 pydantic>=2.0
  2. 检查你使用的请求格式是否正确
  3. API 可能已经更新 —— 试着升级 SDK:pip install --upgrade kaleido-sdk
症状: httpx.ConnectError 或类似报错解决办法:
  1. 检查 API URL 是否可达
  2. 如果使用代理,请通过环境变量配置:HTTP_PROXY、HTTPS_PROXY
  3. 如果连接较慢,请增大超时时间

错误参考

两个 SDK 使用几乎完全一致的错误类层级。所有错误都继承自 KaleidoError,因此只要捕获它,就不会有 SDK 错误漏网:
写处理逻辑之前,有两处差异值得注意:
  • RateLimitError 在 TypeScript 中继承 APIError,而在 Python 中直接继承 KaleidoError —— Python 里的 except APIError 处理块捕获不到速率限制错误。
  • 未配置节点 URL 在 Python 中抛出 NodeNotConfiguredError,而在 TypeScript 中抛出 ConfigError(“Node API not configured. Provide “nodeUrl” when creating the client.”)。

KaleidoError 属性

无论具体是哪个类,每个错误都带有以下属性:

错误类

哪些错误可以安全重试,取决于状态码而不是类本身 —— 见下方的 HTTP 错误映射。

HTTP 错误映射

SDK 通过 mapHttpError / map_http_error 自动把 HTTP 错误映射为带类型的异常: 不要把这张表硬编码进你自己的重试逻辑,而应调用 isRetryable() / is_retryable() —— 它精确编码了这些规则,并会随映射关系的演进保持正确。

完整的错误处理

从最具体的类向最一般的类逐层分支,并以 KaleidoError 收尾,以免有错误漏网。子类必须写在父类之前 —— 在 TypeScript 中 RateLimitError 属于 APIError,如果 APIError 分支写在前面,它会把前者一并吞掉。
只有当某个类的处理方式确实不同时,才值得为它单独开一个分支 —— 比如用 InsufficientBalanceError 展示差额,用 ValidationError 指出出错的字段。其余情况已经被 isRetryable() 判断和兵底分支覆盖。

重试模式

使用 isRetryable() 实现自动重试:

调试

开启详细日志

Python 可以直接使用底层 httpx 与 websockets 的日志器:
TypeScript 没有针对传输层的同类开关。创建客户端时传入更低的 logLevel 可以拿到 SDK 自身的输出 —— 见配置;要看具体的请求,请使用 NODE_DEBUG=http,或浏览器 DevTools 的网络面板。

校验配置

当调用失败但还定位不到具体错误时,按顺序检查这四项:
1

API URL 能否解析

在浏览器中打开 <baseUrl>/api/v1/market/assets。/api/v1 由 SDK 自动追加,因此配置值本身不能包含它。
2

客户端是否看得到节点

只要缺少 nodeUrl / node_url,client.hasNode() / client.has_node() 就返回 false,所有 client.rln.* 调用都会因此失败。
3

节点是否响应

client.rln.getNodeInfo() / get_node_info() 能返回 pubkey,就证明节点既可达又已解锁。
4

两者是否在同一网络

signet 的 baseUrl 配上主网节点,得到的是令人困惑的空结果,而不是一个清晰的错误。

获取帮助

如果是疑问而不是报错,请查阅常见问题;上游文档与相关链接见更多资源。 其他情况请通过下面你偏好的渠道反馈问题,并附上:
  1. SDK 版本(getVersion() / get_version())
  2. 语言与运行时版本(Node.js / Python)
  3. 错误信息与堆栈跟踪
  4. 可复现问题的最小代码
  5. 运行环境(signet / 主网)

Telegram 社区

向社区提问。

GitHub Issues

在相应的仓库中报告缺陷。

邮件支持

紧急问题的直接支持渠道。