错误与调试说明

TRON API 错误需要先按发生阶段分类。不同阶段代表交易处于不同状态，重试策略也不同：

• HTTP 层错误：请求在到达 TRON 节点前，在网络传输或网关层发生的故障。
• 校验错误：节点在正式执行交易前，在预校验阶段拒绝了交易。广播响应通过 CONTRACT_VALIDATE_ERROR、SIGERROR、BANDWITH_ERROR 等顶层错误码分类，并附带错误消息；消息的返回形式取决于 visible。
• 链上执行错误：交易已成功通过校验并被打包进区块，但在链上实际执行时发生失败（如 TVM Revert、资源耗尽等）。这类错误的明细体现在交易回执中，而非接口广播的响应里。

⚠️

注意

生产环境必须区分上述三类错误，并分别处理。混淆错误阶段可能导致严重问题。例如，广播结果未知时，如果未先核对原 txID 就创建替代交易，可能导致重复转账或重复的链上状态变更。

📘

前置阅读

• 交易签名与广播——API 工作流
• 地址与数据编码

1. HTTP 层错误（网络与传输故障）

这类错误通常意味着请求没有完成一次完整往返，客户端没有拿到 TRON 节点返回的 JSON 业务响应。

📘

说明

客户端没有收到业务响应，并不能证明节点尚未接收或处理请求。读请求通常可以重试；对于交易广播，应重播完全相同的已签名交易，以保持 txID 不变。其他可能改变状态的写请求应先查询链上或节点状态，再决定是否重试。

2. 节点预校验错误

这类错误发生在节点已接收并解析请求之后、交易进入交易内存池（Mempool）之前。也就是说，交易未成功进入网络等待打包。

广播接口返回的失败响应通常如下所示：

{
  "code": "CONTRACT_VALIDATE_ERROR",
  "message": "636f6e7472616374207061726168657920646f6573206e6f74206d61746368"
}

/wallet/broadcasttransaction 失败时通常会省略默认值为 false 的 result 字段。响应中的 code 表示失败类别，message 提供具体原因。未设置 visible 或将其设为 false 时，该字段通常采用十六进制编码；设置为 true 时，节点可能直接返回 UTF-8 明文。

常见顶层广播错误码

BANDWITH_ERROR 沿用协议枚举中的拼写，客户端必须按该原值匹配。

解码十六进制错误消息

收到十六进制形式的 message 时，可按以下方式解码；如果节点已经返回明文，则直接使用原值：

const message = "636f6e747261637420706172616d6574657220646f6573206e6f74206d61746368";
const decoded = /^(?:[0-9a-fA-F]{2})+$/.test(message)
  ? Buffer.from(message, "hex").toString("utf8")
  : message;
console.log(decoded);
// 输出: "contract parameter does not match"

💡

提示

多数 SDK 会自动解码错误消息。业务直接处理 HTTP API 响应时，应先判断格式再决定是否解码，避免把节点返回的明文误当作十六进制数据。

常见的校验错误类型与解决方案

3. 链上执行阶段错误

智能合约交易即使通过节点预校验并被打包，仍可能在虚拟机（TVM）执行阶段失败。此类执行结果记录在交易收据（Transaction Receipt）中，可通过以下接口查询已固化的执行结果：

POST /walletsolidity/gettransactioninfobyid
Content-Type: application/json

{ "value": "<txid>" }

查询返回后，应先确认顶层 result 未标记为 FAILED，再通过 receipt.result 判断 TVM 执行结果。receipt.result 的完整状态码枚举定义在底层的 protocol/src/main/protos/core/Tron.proto 文件中，详情如下：

💡

提示

当 receipt.result 返回 REVERT 时，可以进一步提取交易响应中 contractResult[0] 字段的数据。该数据遵循 Solidity 标准的 Error(string) 错误信息 ABI 编码格式，经解码后即可还原出合约抛出的具体文字原因（如 "Insufficient allowance"）。

业务重试策略

针对不同类别的错误，业务系统应当实施针对性的重试处理方案：

交易幂等性设计

为 TRON 网络开发高并发支付或写入系统时，需要建立两项幂等与状态确认防线：

1. 重复广播已签名的相同交易是安全的：TRON 全网通过 txID 做唯一性去重。完全相同的已签名交易始终具有同一 txID，不会导致交易执行两次；节点发现重复交易时可能返回 DUP_TRANSACTION_ERROR。广播后如果因网络超时或服务端 5xx 未能确认结果，可以重播同一笔交易，但不要立即创建新的替代交易。
2. 广播调用未报错不等于交易成功：result: true 只表示本次广播调用未返回错误。应保留原 txID 并查询已固化结果：普通 TRX 或 TRC-10 转账查询 /walletsolidity/gettransactionbyid，智能合约交易还需查询 /walletsolidity/gettransactioninfobyid。接口选择与返回数据的含义参见确认语义。

对于已经广播或广播结果未知的交易，不要直接创建替代交易。应按照交易安全重播与替换流程，使用能够查询原交易可能上链区间内所有已固化区块的数据源核对原 txID。只有在最新固化区块时间达到原交易的 raw_data.expiration，且所有相关区块中均未发现原交易后，才能重新构建。本地时间超过 raw_data.expiration、查询超时或 /walletsolidity/gettransactionbyid 单次返回空对象 {}，都不能证明原交易未上链。

常用调试 Endpoint

💡

提示

编写智能合约或开发 DApp 时，建议在正式提交交易前使用 /wallet/triggerconstantcontract 模拟执行。该接口本身不要求传入交易级 fee_limit；可将返回的 energy_used 按当前 getEnergyFee 换算后，与计划设置的 fee_limit 比较，从而提前发现预算过低的风险。

相关资源

• 交易签名与广播——API 工作流 —— 拆解交易构建、签名与广播各个环节潜在的出错点与生命周期
• 地址与数据编码 —— 详细了解编码规范以避免最易发生的格式校验错误
• 资源模型 —— 带宽、能量资源成本以及 fee_limit 的设置方式
• 智能合约异常排查 —— 根据具体错误消息判断 OUT_OF_TIME 是由执行超时还是协议检查触发
• 常见问题 FAQ —— 总结自 TRON 社区和生态开发者的经典疑难错误解答