TronEnergy API 错误代码与故障排除

每个错误响应都有两个字段：error（机器可读，稳定，版本间不会变化）和 message（人类可读，可能会随时间改进）。始终在代码中使用 error 进行判断。向用户显示 message。

错误格式

所有错误响应都遵循相同的结构：

错误响应

    {
      "error": "error_code_here",
      "message": "Human-readable explanation"
    }
  

某些错误包含额外字段：ref（委托能量尝试的参考 ID）和refund（自动退款的详情）。

验证错误

错误代码	HTTP	原因	解决方案
`invalid_tx_hash`	400	tx_hash 不是 64 字符的十六进制字符串	检查哈希格式。必须恰好为 64 个十六进制字符，无前缀。
`invalid_address`	400	delegate_to 不是有效的 Tron 地址	调用前用 TronWeb.isAddress() 验证地址。
`missing_signature`	400	请求中未提供签名	使用`{tx_hash}:{delegate_to}`签署消息`tronWeb.trx.signMessageV2()`来自发送 TRX 的钱包。
`invalid_signature`	401	无法验证签名	确保您签署了`{tx_hash}:{delegate_to}`（小写十六进制哈希、冒号、精确 Tron 地址）。
`signature_mismatch`	403	签名人地址与支付发送人不匹配	签名必须来自发送 TRX 支付的同一钱包。不同钱包 = 拒绝。

支付错误

错误代码	HTTP	原因	解决方案
`payment_verification_failed`	404 / 400	无法验证链上支付。`message`字段描述了具体原因。	常见原因：交易未确认（等待 3-5 秒后重试一次）、收款地址错误、交易不是 TRX 转账、低于 4 TRX 最低额度。
`hash_already_used`	409	此交易哈希已被领取	每个支付哈希只能使用一次。新的委托需要发送新的支付。

服务错误

错误代码	HTTP	原因	解决方案
`delegation_failed`	400 / 500	提供商无法交付能量委托	如果失败发生在您的支付被验证之后，自动退款已排队。检查`refund` 对象。否则请重试，或联系支持团队。`ref` ID。
`rate_limited`	429	来自此IP的请求过于频繁	减速并重试。限制为每秒 20 个请求。
`server_error`	500	意外的内部错误	几秒后重试。如果问题持续，请联系支持团队。`ref` （如果可用）。

在代码中处理错误

推荐的错误处理

    const result = await fetch('https://api.tronnrg.com/delegate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ tx_hash: hash, delegate_to: addr, signature: sig }),
    }).then(r => r.json());
    
    if (result.error) {
      switch (result.error) {
        case 'payment_verification_failed':
          // Most common: tx not yet indexed. Wait 3s and retry once.
          await new Promise(r => setTimeout(r, 3000));
          return retry(hash, addr);
    
        case 'hash_already_used':
          // Already claimed. Don't retry.
          throw new Error('Duplicate delegation attempt');
    
        case 'signature_mismatch':
          // Signer != payment sender. Sign with the same key.
          throw new Error('Signer does not match payment sender');
    
        case 'delegation_failed':
          // Refund queued automatically if payment was verified.
          if (result.refund) console.log('Refund queued:', result.refund);
          break;
    
        default:
          console.error(result.error, result.message);
      }
      return;
    }
    
    // Success
    console.log('Delegated:', result.energy, 'energy');
  console.log('Delegation tx:', result.delegations[0].tx);  // verify on TronScan
  console.log('Ref:', result.ref);
  