指南API 参考手册社区Discord博客FAQ漏洞赏金公告中心
指南
English(英文版)

广播与 RPC 错误诊断

TRON 节点如何反馈交易广播失败和 RPC 限频。涵盖完整的广播响应码对照表、SERVER_BUSY 内存池溢出处理、TronGrid 503 限流响应,以及广播成功后始终未上链的诊断。

📘

前置阅读

本文归纳客户端向 TRON 节点广播交易时可能遇到的报错类型,以及托管 RPC 网关返回限频响应时的处理对策。

⚠️

注意

交易被打包进区块之后发生的异常(如 TVM Revert、OutOfEnergy 资源耗尽、OutOfTime 执行超时等链上执行失败),见智能合约错误说明。报错整体分类与 Hex 错误消息解码细节,见错误与调试说明。

交易广播接口响应码

客户端调用 /wallet/broadcasttransaction 失败时,响应体返回顶层 code 字段。节点可能返回的完整响应码对照如下:

广播响应码具体失败原因推荐排查与修复方法
SIGERROR交易签名验证未通过检查用于签名的私钥是否与发送方的 TRON 地址相匹配，并核对私钥的十六进制字符格式是否正确。
BANDWITH_ERROR广播前 Bandwidth 不足，或 TRX 余额不足以支付 Bandwidth、新账户创建、多签、Memo 等费用；不表示 TVM 执行阶段 Energy 不足查询 /wallet/getaccountresource 和 /wallet/getchainparameters，结合交易是否创建账户、包含多签或 Memo 判断具体费用，并补充 Bandwidth 或 TRX。
DUP_TRANSACTION_ERROR相同 txID 通常已进入当前节点的 Pending Pool 或区块。若节点启用了 node.rpc.trxCacheEnable，也可能只是广播缓存命中先按原 txID 查询交易及收据。无论是否启用 RPC 交易缓存，该错误都不能证明交易已上链。在有效期内可向其他可靠的同步节点重播同一笔已签名交易；仅在交易已过期且确认未上链时重新构建，避免重复付款。
TAPOS_ERROR交易引用的 TAPOS 区块号与哈希无法在当前节点的近期区块记录中匹配使用当前同步节点认可的近期区块重新构造交易，最新固化块通常更稳妥。
TOO_BIG_TRANSACTION_ERROR交易数据的字节大小超出了网络单笔上限常见于备注（Memo）字段过长。请缩减备注信息或拆分交易以缩减单笔字节大小。
TRANSACTION_EXPIRATION_ERROR交易在进入节点的交易内存池前已超出有效期限。默认有效期为 60 秒尽量缩短构建、本地签名与广播这三步之间的等待延迟。在节点侧，可以通过 config.conf 配置项调大 trx.expiration.timeInMilliseconds；而在公共 API 下该窗口无法调高，必须在 60 秒内完成广播。
SERVER_BUSY节点系统繁忙，或其待处理池（Pending Pool）已满请参阅下方 SERVER_BUSY 异常处理。
NOT_ENOUGH_EFFECTIVE_CONNECTION目标节点自身尚未同步到最新的区块高度比较 wallet/getnowblock 返回的高度与区块浏览器上当前的最新高度。若落后严重，请等待节点同步追上，或在客户端配置中切换到其他完全同步的节点。
OTHER_ERROR系统未分类的未知异常需要查阅全节点的本地后台日志以获取详细异常堆栈。
NO_CONNECTION该节点未建立起足够的 P2P 网络连接请检查配置文件中的 seed.node 种子节点列表，并尝试重启节点。
CONTRACT_EXE_ERROR合约在静态预执行阶段因运行时异常或非法 Protobuf 结构而执行失败检查合约调用的入参格式和 ABI 编码，并查阅节点的运行日志。
BLOCK_UNSOLIDIFIED节点上的未固化区块数量过多（超出了配置阈值）等待节点后台自动落账恢复。如果是自建节点，可通过修改 node.maxUnsolidifiedBlocks 调大容量限制，或通过 node.unsolidifiedBlockCheck 禁用该项安全检查。
CONTRACT_VALIDATE_ERROR预执行阶段的静态校验未通过（系统合约层校验）具体的失败原因存放在 message 字段中，并采用了十六进制编码。请使用十六进制转字符串工具进行解码。参见下方 CONTRACT_VALIDATE_ERROR 详细解析。

CONTRACT_VALIDATE_ERROR 详细解析

该错误码是一个通用的静态校验失败标识，真正的底层业务原因通常存放在 message 字段中。对十六进制消息进行解码后，最常见的明文含义如下:

解码后的明文消息原因说明解决方案
account does not exist签名发送方或接收方的账户在链上不存在（从未被激活过）。需要向该账户转入任意小额 TRX（如 1 sun）以在链上激活创建该账户。
Validate ... error, no OwnerAccount请求中传入的 owner_address（发送方地址）格式非法或不存在。检查地址编码格式是否正确（如 visible 参数配置，参见编码指南）。
No contract or not a valid smart contract目标合约地址错误，或者该地址在链上并不是一个智能合约账户。仔细核对部署的合约地址是否正确，避免指向普通外部账户（EOA）。
this node does not support constant当前连接的节点不支持只读合约常量调用（Constant Call）。常见于自托管全节点的配置未开启。请参阅节点运维指南以及 config.conf 配置文件中的 vm.supportConstant 参数说明。

SERVER_BUSY — 交易内存池溢出

TRON 全节点积压的未处理交易超过上限(默认通常为 2,000 笔)时,接收新的广播请求就返回 SERVER_BUSY。

修复方案(自建节点):
节点运维方修改 config.conf 中的参数,提高内存池上限(按服务器内存与 CPU 水位合理调优):

node.maxTransactionPendingSize = 5000
📘

说明

使用 TronGrid 等托管 RPC 服务时,响应里出现 SERVER_BUSY,通常表明生态正发生高并发的全局交易热点。此时在客户端引入指数退避重试,或切换到备用池中其他 RPC 提供商的 Endpoint。

TronGrid 503 限流与服务不可用

TronGrid 对所有 HTTP 请求按 IP 和 API Key 限频。访问速率超过配额时,TronGrid 拒绝服务并返回 HTTP 4xx 或 5xx 错误码(最常见的是 HTTP 503 Service Unavailable)。

推荐的修复与优化对策:

  1. 务必在请求头携带 TRON-PRO-API-KEY：未携带 API Key 的请求频次阈值极低,很容易触发限流。Header 携带格式见 TronGrid 速率限制。
  2. 优化客户端请求频次:降低 DApp 启动时的突发并发。不要以快于出块的速度轮询节点——TRON 主网出块间隔 3 秒,快于 3 秒的轮询没有业务意义。
  3. 严格遵守 Retry-After 响应头:503 响应包含 Retry-After 头时,客户端必须等待其指定时间后再重试。详见重试策略说明。
  4. 升级套餐或混合方案:高流量的生产业务,可在 TronGrid 控制台提交定制申请提升 API Key 的 QPS 上限,或采用自建节点 + 第三方托管 RPC 的混合配置。

交易广播成功但始终未打包上链

调用广播接口后,API 已返回 {"result": true, "txid": "..."},但经过数十个出块间隔,用交易哈希调 gettransactioninfobyid 仍返回空数据。

主要原因：
交易已通过广播节点校验、进入本地内存池,但未能传播分发到出块的超级代表(SR)节点。这通常是广播节点与主网 SR 集群之间网络不稳定,或节点遭遇广播分区隔离(Forks/Network Partition)。

推荐的处理流：

  1. 等待过期窗口关闭：单笔交易构建后有约 60 秒有效期。超过期限后,该交易确定作废,不会再被网络打包。
  2. 有效期内多节点重传:交易未过期时,把已本地签名的完整交易对象提交到其他多个同步节点广播。TRON 底层按 txID 做幂等去重,向不同节点重复广播同一笔已签名交易无害,还能提高全网传播概率。
  3. 过期后重新构建并签名:确认过期后,不要复用旧的交易哈希和 raw_data。应基于当前节点认可的近期区块和当前时间戳重新构建交易,再签名、广播；使用固化块是一种更保守的选择，但不是协议的唯一合法选择。
⚠️

重要

广播返回 result: true 仅代表交易进入了节点内存池，不代表交易已最终打包并执行成功。 业务系统判定充值入账等状态时,必须通过 /walletsolidity/gettransactioninfobyid(已固化的安全路径)查询到明确的 Receipt,才能视为最终上链状态。

相关资源

Updated 5 days ago