Codes d'erreur de l'API TronEnergy et dépannage

Chaque réponse d'erreur a deux champs : error (lisible par la machine, stable, ne change jamais entre les versions) et message (lisible par l'homme, peut être amélioré au fil du temps). Basculez toujours sur error dans votre code. Affichez message aux utilisateurs.

Format d'erreur

Toutes les réponses d'erreur suivent la même structure :

réponse d'erreur

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

Certaines erreurs incluent des champs supplémentaires : ref (un identifiant de référence pour la tentative de délégation d'énergie) et refund (détails concernant un remboursement automatique).

Erreurs de Validation

Code d'Erreur	HTTP	Cause	Résolution
`invalid_tx_hash`	400	tx_hash n'est pas une chaîne hexadécimale de 64 caractères	Vérifiez le format du hash. Doit être exactement 64 caractères hexadécimaux, sans préfixe.
`invalid_address`	400	delegate_to n'est pas une adresse Tron valide	Validez l'adresse avec TronWeb.isAddress() avant d'appeler.
`missing_signature`	400	Aucune signature fournie dans la requête	Signez le message `{tx_hash}:{delegate_to}` avec `tronWeb.trx.signMessageV2()` du portefeuille qui a envoyé le TRX.
`invalid_signature`	401	La signature n'a pas pu être vérifiée	Assurez-vous que vous avez signé exactement `{tx_hash}:{delegate_to}` (hash hexadécimal minuscule, deux-points, adresse Tron exacte).
`signature_mismatch`	403	L'adresse du signataire ne correspond pas à l'émetteur du paiement	La signature doit provenir du même portefeuille qui a envoyé le paiement en TRX. Portefeuille différent = rejeté.

Erreurs de Paiement

Code d'Erreur	HTTP	Cause	Résolution
`payment_verification_failed`	404 / 400	Le paiement on-chain n'a pas pu être vérifié. Le champ `message` décrit la cause spécifique.	Causes courantes : tx pas encore confirmée (attendez 3-5 secondes et réessayez une fois), mauvaise adresse de destinataire, la transaction n'est pas un transfert TRX, en dessous du minimum de 4 TRX.
`hash_already_used`	409	Ce hash tx a déjà été utilisé	Chaque hash de paiement ne peut être utilisé qu'une seule fois. Envoyez un nouveau paiement pour une nouvelle délégation d'énergie.

Erreurs de Service

Code d'Erreur	HTTP	Cause	Résolution
`delegation_failed`	400 / 500	Le fournisseur n'a pas pu livrer la délégation d'énergie	Si l'échec s'est produit après la vérification de votre paiement, un remboursement automatique est en file d'attente. Vérifiez le `refund` objet. Sinon, réessayez ou contactez le support avec le `ref` ID.
`rate_limited`	429	Trop de requêtes depuis cette adresse IP	Ralentissez et réessayez. La limite est de 20 requêtes par seconde.
`server_error`	500	Erreur interne inattendue	Réessayez après quelques secondes. Si le problème persiste, contactez le support avec le `ref` si disponible.

Gérer les erreurs dans le code

gestion recommandée des erreurs

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