错误代码 | TronEnergy Docs

每个错误响应都包含两个字段：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 不是有效的波场地址	调用前先用 TronWeb.isAddress() 校验地址。
`missing_signature`	400	请求中未提供签名	用发送 TRX 的钱包，通过 `{tx_hash}:{delegate_to}` 对消息 `tronWeb.trx.signMessageV2()` 签名。
`invalid_signature`	401	签名无法验证	确认您签名的内容与 `{tx_hash}:{delegate_to}` 完全一致（小写十六进制哈希、冒号、准确的波场地址）。
`signature_mismatch`	403	签名者地址与付款发送方不一致	签名必须来自发送 TRX 付款的同一个钱包。换了钱包就会被拒绝。

付款错误

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

服务错误

错误代码	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);
  