Коди помилок TronEnergy API та усунення неполадок

Кожна відповідь про помилку має два поля: 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 — це не коректна адреса Tron	Перевірте адресу за допомогою TronWeb.isAddress() перед викликом.
`missing_signature`	400	У запиті не надано підпису	Підпишіть повідомлення `{tx_hash}:{delegate_to}` за допомогою `tronWeb.trx.signMessageV2()` з гаманця, який відправив TRX.
`invalid_signature`	401	Не вдалося перевірити підпис	Переконайтеся, що ви підписали точно `{tx_hash}:{delegate_to}` (малий шістнадцятковий хеш, двокрапка, точна адреса Tron).
`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);
  