错误码对照表
TronLink 智能体在一次用户请求里跨 DApp provider → DeepLink → MCP → CLI 时,会先后碰到三四套错误码方言。本页是以业务含义为主轴的横向对照,用来把任一方言里的错误码翻译到其他方言,并判断重试是否安全。
各列表头链接的"每个 surface 自己的错误表"仍然是 SSOT,本页只是导航工具——遇到歧义时,以你实际调用的那个 surface 的结构化字段为准(MCP / CLI /
--json看error.code;provider 看 JS Error 的code;DeepLink 看回调里的code)。
| 业务含义 | DApp provider(EIP-1474) | DeepLink(5 位码) | MCP(TL_*) | CLI(exit code) | 可重试? |
|---|---|---|---|---|---|
| 用户拒绝签名或连接弹窗 | 4001 | 300(交易取消) | —(HITL——只能在新的 tool 调用里再次唤起) | 2 | 否 |
| 参数非法 / payload 错 | tronWeb 构造器抛错 | 10001–10020、10024、10025 | TL_INVALID_INPUT | 1 | 否——修参数 |
| 方法 / capability 不支持 | 4200 | 10003、10008、10009、10011、10023 | TL_CAPABILITY_NOT_AVAILABLE | — | 否 |
| 钱包授权不匹配(发起地址 ≠ 当前钱包) | provider 返回空 accounts[] | 10021、10022 | — | — | 否——重新授权 |
| 没有钱包 / 无会话 | provider 未注入(window.tron 不存在) | 10016 | TL_NO_ACTIVE_SESSION | — | 否——先初始化 / tl_launch |
| 限流 / 钱包锁定 | -32000(20 秒内重复 eth_requestAccounts 且钱包锁定) | — | — | — | 是——等一会儿再试 |
| 网络 / RPC 抖动(TronGrid、RPC 错) | tronWeb 调用里的 TronGrid HTTP 错 | — | TL_CHAIN_QUERY_FAILED、TL_GASFREE_QUERY_FAILED、TL_MULTISIG_QUERY_FAILED | 5 | 是 |
链上执行失败(广播后:REVERT、OUT_OF_ENERGY、FAILED) | sendRawTransaction 抛错或经 getTransactionInfo 暴露 | — | TL_CHAIN_SEND_FAILED、TL_CHAIN_SWAP_FAILED、TL_GASFREE_SEND_FAILED、TL_MULTISIG_SUBMIT_FAILED | 4 | 否——交易已 final;查根因;永远不要自动重试写操作 |
| 超时(用户没及时签 / 元素找不到) | 调用解析慢,无规范化的码 | — | TL_WAIT_TIMEOUT、TL_NAVIGATION_FAILED | 3 | 视情况——读操作可以;可能已被广播的写操作先用 tronWeb.trx.getTransactionInfo / tl_chain_get_tx 对账后再决定 |
| 内部 / 未知 | -32603(Internal error) | — | TL_INTERNAL_ERROR、TL_LAUNCH_FAILED | — | 可重试一次——再失败带 log 上报 |
使用方式
- 在任一 surface 收到错误后,在表里找到对应的业务含义行,横向读出其他 surface 的对应码(或空白)。
- 可重试? 列是给智能体的安全提示:
- 否——自动重试会失败甚至有害。最危险的是"链上执行失败",此时交易已上链,无法撤回。
- 是——临时性问题,退避(指数,最多 3 次)后重试原调用。
- 视情况——读操作可以重试;写操作不要在没对账的情况下自动重试。
- DeepLink 和 CLI 两列有很多空白,是因为这两个 surface 只覆盖了生命周期的一段——DeepLink 仅限移动端且跨信任边界;CLI 的 exit code 把 MCP 的多个
TL_*折成一类。用得到哪个 surface 就以哪个 surface 为准。
给下游 MCP 服务的约束
下游 MCP 服务(TronLink Signer、自定义 Skills)必须复用本表里的 TL_* 码,不要自创新字符串。如果出现了新的业务含义,先在本页加行 + 在 tronlink-mcp-core(SSOT)加新的 TL_* 常量,再在消费端引用——不要在消费端临时造码。