错误与调试说明

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

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

⚠️

注意

生产环境必须区分上述三类错误，并分别处理。混淆错误阶段可能导致严重问题。例如，盲目重试一笔已广播但执行时触发 Revert 的交易，可能在链上状态变化后引发重复操作或业务状态错乱。

📘

前置阅读

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

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

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

📘

说明

HTTP 层错误属于纯粹的传输层故障，交易数据尚未被 TRON 节点接收或处理。因此，在此类情况下可以安全地直接重试相同的请求 Payload，不会存在因重复广播导致交易被二次打包执行的风险。

2. 节点预校验错误（CONTRACT_VALIDATE_ERROR）

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

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

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

响应中的 code 字段表示校验失败的粗粒度大类（例如 CONTRACT_VALIDATE_ERROR、SIGERROR、BANDWITH_ERROR 等）。而导致失败的具体业务原因，则存放在 message 字段中，并以十六进制 Hex 格式进行了编码。

解码十六进制错误消息

为了在开发或日志系统中查看明文错误，需要对 message 进行 Hex 解码：

const hex = "636f6e7472616374207061726168657920646f6573206e6f74206d61746368";
const decoded = Buffer.from(hex, "hex").toString("utf8");
console.log(decoded);
// 输出: "contract parahey does not match"

💡

提示

多数 SDK 会自动解码错误消息。如果日志中出现大段十六进制字符串，通常说明业务直接处理了原始 HTTP API 响应。对外告警或展示给前端用户前，应先完成解码转换。

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

3. 链上执行阶段错误

请记住：交易被打包进区块不等于交易执行成功。交易即使通过节点预校验并记录在链上，仍可能在虚拟机（TVM）执行阶段失败。要确认最终结果，必须查询交易收据（Transaction Receipt）：

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

{ "value": "<txid>" }

查看返回结构体中的 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，不会导致该交易被打包或执行两次。广播后如果因网络超时或服务端 5xx 未能确认结果，可以重试广播同一笔交易。
2. 广播成功不等于交易最终落账：成功广播只代表交易进入节点交易内存池。在将资金变化或状态变更视为最终结果前，必须通过 /walletsolidity/gettransactioninfobyid 查询已固化数据，并确认 Receipt 为 SUCCESS。

常用调试 Endpoint

💡

提示

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

相关资源

• 交易签名与广播——API 工作流 —— 拆解交易构建、签名与广播各个环节潜在的出错点与生命周期
• 地址与数据编码 —— 详细了解编码规范以避免最易发生的格式校验错误
• 资源模型 —— 带宽、能量资源成本以及 fee_limit 的设置方式
• 常见问题 FAQ —— 总结自 TRON 社区和生态开发者的经典疑难错误解答