Códigos de Erro da API TronEnergy & Solução de Problemas

Toda resposta de erro tem dois campos: error (legível por máquina, estável, nunca muda entre versões) e message (legível por humanos, pode ser melhorado ao longo do tempo). Sempre use switch em error no seu código. Exiba message para os usuários.

Formato de Erro

Todas as respostas de erro seguem a mesma estrutura:

resposta de erro

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

Alguns erros incluem campos adicionais: ref (um ID de referência para a tentativa de delegação) e refund (detalhes sobre um reembolso automático).

Erros de Validação

Código de Erro	HTTP	Causa	Solução
`invalid_tx_hash`	400	tx_hash não é uma string hexadecimal de 64 caracteres	Verifique o formato do hash. Deve ser exatamente 64 caracteres hexadecimais, sem prefixo.
`invalid_address`	400	delegate_to não é um endereço Tron válido	Valide o endereço com TronWeb.isAddress() antes de fazer a chamada.
`missing_signature`	400	Nenhuma assinatura fornecida na requisição	Assine a mensagem `{tx_hash}:{delegate_to}` com `tronWeb.trx.signMessageV2()` da carteira que enviou o TRX.
`invalid_signature`	401	A assinatura não pôde ser verificada	Certifique-se de ter assinado exatamente `{tx_hash}:{delegate_to}` (hash hexadecimal em minúsculas, dois-pontos, endereço Tron exato).
`signature_mismatch`	403	O endereço do signatário não corresponde ao remetente do pagamento	A assinatura deve vir da mesma carteira que enviou o pagamento em TRX. Carteira diferente = rejeitado.

Erros de Pagamento

Código de Erro	HTTP	Causa	Solução
`payment_verification_failed`	404 / 400	O pagamento on-chain não pôde ser verificado. O campo `message` descreve a causa específica.	Causas comuns: transação ainda não confirmada (aguarde 3-5 segundos e tente novamente), endereço de destinatário incorreto, a transação não é uma transferência de TRX, abaixo do mínimo de 4 TRX.
`hash_already_used`	409	Este hash de transação já foi utilizado	Cada hash de pagamento só pode ser usado uma vez. Envie um novo pagamento para uma nova delegação.

Erros de Serviço

Código de Erro	HTTP	Causa	Solução
`delegation_failed`	400 / 500	O provedor não conseguiu entregar a delegação de energia	Se a falha ocorreu após seu pagamento ser verificado, um reembolso automático será enfileirado. Verifique o `refund` objeto. Caso contrário, tente novamente ou entre em contato com o suporte com o `ref` ID.
`rate_limited`	429	Muitas requisições deste IP	Desacelere e tente novamente. O limite é de 20 requisições por segundo.
`server_error`	500	Erro interno inesperado	Tente novamente após alguns segundos. Se persistir, entre em contato com o suporte com o `ref` se disponível.

Tratamento de Erros em Código

tratamento de erros recomendado

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