Códigos de error y solución de problemas de la API TronEnergy

Cada respuesta de error tiene dos campos: error (legible para máquinas, estable, nunca cambia entre versiones) y message (legible para humanos, puede mejorar con el tiempo). Siempre compara error en tu código. Muestra message a los usuarios.

Formato de error

Todas las respuestas de error siguen la misma estructura:

respuesta de error

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

Algunos errores incluyen campos adicionales: ref (un ID de referencia del intento de delegación) y refund (detalles sobre un reembolso automático).

Errores de Validación

Código de Error	HTTP	Causa	Resolución
`invalid_tx_hash`	400	tx_hash no es una cadena hexadecimal de 64 caracteres	Verifica el formato del hash. Debe tener exactamente 64 caracteres hexadecimales, sin prefijo.
`invalid_address`	400	delegate_to no es una dirección Tron válida	Valida la dirección con TronWeb.isAddress() antes de hacer la llamada.
`missing_signature`	400	No se proporcionó firma en la solicitud	Firma el mensaje `{tx_hash}:{delegate_to}` con `tronWeb.trx.signMessageV2()` desde la billetera que envió los TRX.
`invalid_signature`	401	La firma no pudo ser verificada	Asegúrate de firmar exactamente `{tx_hash}:{delegate_to}` (hash hexadecimal minúsculo, dos puntos, dirección Tron exacta).
`signature_mismatch`	403	La dirección del firmante no coincide con la del remitente del pago	La firma debe provenir de la misma billetera que envió el pago en TRX. Billetera diferente = rechazado.

Errores de Pago

Código de Error	HTTP	Causa	Resolución
`payment_verification_failed`	404 / 400	El pago en cadena no pudo ser verificado. El campo `message` describe la causa específica.	Causas comunes: transacción no confirmada aún (espera 3-5 segundos e intenta de nuevo), dirección de destinatario incorrecta, la transacción no es una transferencia de TRX, por debajo del mínimo de 4 TRX.
`hash_already_used`	409	Este hash de transacción ya ha sido utilizado	Cada hash de pago solo puede usarse una vez. Envía un nuevo pago para una nueva delegación.

Errores de Servicio

Código de Error	HTTP	Causa	Resolución
`delegation_failed`	400 / 500	El proveedor no pudo entregar la delegación de energía	Si el fallo ocurrió después de que tu pago fue verificado, un reembolso automático está en cola. Verifica el `refund` objeto. En caso contrario, reintentas o contacta con soporte con el `ref` ID.
`rate_limited`	429	Demasiadas solicitudes desde esta IP	Ve más lentamente e reintentas. El límite es 20 solicitudes por segundo.
`server_error`	500	Error interno inesperado	Reintentas después de unos segundos. Si persiste, contacta con soporte con el `ref` si está disponible.

Manejo de Errores en Código

gestión de errores recomendada

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