TronEnergy API Error Codes & Troubleshooting

Bawat error response ay may dalawang fields: error (machine-readable, stable, hindi kailanman nagbabago sa pagitan ng versions) at message (human-readable, maaaring mapabuti sa paglipas ng panahon). Laging mag-switch sa error sa iyong code. Ipakita ang message sa mga users.

Error Format

Lahat ng error responses ay sumusunod sa parehong structure:

error response

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

Ang ilang errors ay may karagdagang fields: ref (reference ID para sa delegation attempt) at refund (detalye tungkol sa automatic refund).

Validation Errors

Error Code	HTTP	Sanhi	Solusyon
`invalid_tx_hash`	400	tx_hash ay hindi 64-character hex string	Suriin ang hash format. Dapat eksaktong 64 hex characters, walang prefix.
`invalid_address`	400	delegate_to ay hindi valid na Tron address	I-validate ang address gamit ang TronWeb.isAddress() bago mag-call.
`missing_signature`	400	Walang signature na ibinigay sa request	I-sign ang message `{tx_hash}:{delegate_to}` gamit ang `tronWeb.trx.signMessageV2()` mula sa wallet na nagpadala ng TRX.
`invalid_signature`	401	Hindi ma-verify ang signature	Siguraduhin na i-sign mo ang eksaktong `{tx_hash}:{delegate_to}` (lowercase hex hash, colon, exact Tron address).
`signature_mismatch`	403	Ang signer address ay hindi tumutugma sa payment sender	Ang signature ay dapat mula sa parehong wallet na nagpadala ng TRX payment. Ibang wallet = rejected.

Payment Errors

Error Code	HTTP	Sanhi	Solusyon
`payment_verification_failed`	404 / 400	Hindi ma-verify ang on-chain payment. Ang `message` field ay naglalarawan ng specific cause.	Karaniwang sanhi: tx hindi pa confirmed (maghintay 3-5 segundo at subukan ulit), maling recipient address, transaction ay hindi TRX transfer, mas mababa sa 4 TRX minimum.
`hash_already_used`	409	Ang tx hash na ito ay na-claim na	Bawat payment hash ay maaaring gamitin lang minsan. Magpadala ng bagong payment para sa bagong delegation.

Service Errors

Error Code	HTTP	Sanhi	Solusyon
`delegation_failed`	400 / 500	Hindi kayang i-deliver ng provider ang energy delegation	Kung ang failure ay nangyari pagkatapos ma-verify ang payment mo, isang automatic refund ay nakaqueue. Suriin ang `refund` object. Otherwise retry, o makipag-ugnayan sa support kasama ang `ref` ID.
`rate_limited`	429	Masyadong maraming requests mula sa IP na ito	Magpahinga at subukan ulit. Ang limit ay 20 requests per second.
`server_error`	500	Unexpected internal error	Subukan ulit pagkatapos ng ilang segundo. Kung patuloy pa rin, makipag-ugnayan sa support kasama ang `ref` kung available.

Paghawak ng Errors sa Code

inirekomendang error handling

    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);
  