Mã Lỗi TronEnergy API & Xử Lý Sự Cố

Mỗi phản hồi lỗi có hai trường: error (có thể đọc được bằng máy, ổn định, không bao giờ thay đổi giữa các phiên bản) và message (có thể đọc được bằng con người, có thể được cải thiện theo thời gian). Luôn chuyển đổi error trong mã của bạn. Hiển thị message cho người dùng.

Định Dạng Lỗi

Tất cả các phản hồi lỗi tuân theo cùng một cấu trúc:

phản hồi lỗi

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

Một số lỗi có chứa các trường bổ sung: ref (ID tham chiếu cho nỗ lực ủy quyền năng lượng) và refund (chi tiết về hoàn tiền tự động).

Lỗi Xác Thực

Mã Lỗi	HTTP	Nguyên Nhân	Giải Pháp
`invalid_tx_hash`	400	tx_hash không phải là chuỗi hex 64 ký tự	Kiểm tra định dạng hash. Phải chính xác 64 ký tự hex, không có tiền tố.
`invalid_address`	400	delegate_to không phải là địa chỉ Tron hợp lệ	Xác thực địa chỉ bằng TronWeb.isAddress() trước khi gọi.
`missing_signature`	400	Không có chữ ký trong yêu cầu	Ký pesan `{tx_hash}:{delegate_to}` với `tronWeb.trx.signMessageV2()` từ ví đã gửi TRX.
`invalid_signature`	401	Không thể xác minh chữ ký	Đảm bảo bạn đã ký chính xác `{tx_hash}:{delegate_to}` (hex hash viết thường, dấu hai chấm, địa chỉ Tron chính xác).
`signature_mismatch`	403	Địa chỉ người ký không khớp với người gửi thanh toán	Chữ ký phải đến từ cùng ví đã gửi thanh toán TRX. Ví khác = bị từ chối.

Lỗi Thanh Toán

Mã Lỗi	HTTP	Nguyên Nhân	Giải Pháp
`payment_verification_failed`	404 / 400	Không thể xác minh thanh toán trên chuỗi. Trường `message` mô tả nguyên nhân cụ thể.	Nguyên nhân phổ biến: giao dịch chưa được xác nhận (chờ 3-5 giây và thử lại), địa chỉ nhận sai, giao dịch không phải chuyển TRX, dưới mức tối thiểu 4 TRX.
`hash_already_used`	409	Hash giao dịch này đã được yêu cầu	Mỗi hash thanh toán chỉ có thể được sử dụng một lần. Gửi thanh toán mới để ủy quyền năng lượng mới.

Lỗi Dịch Vụ

Mã Lỗi	HTTP	Nguyên Nhân	Giải Pháp
`delegation_failed`	400 / 500	Nhà cung cấp không thể cung cấp ủy quyền năng lượng	Nếu lỗi xảy ra sau khi thanh toán của bạn được xác minh, hoàn tiền tự động sẽ được xếp hàng. Kiểm tra `refund` đối tượng. Nếu không, hãy thử lại hoặc liên hệ hỗ trợ với `ref` ID.
`rate_limited`	429	Quá nhiều yêu cầu từ IP này	Giảm tốc độ và thử lại. Giới hạn là 20 yêu cầu mỗi giây.
`server_error`	500	Lỗi nội bộ không mong muốn	Thử lại sau vài giây. Nếu còn tiếp diễn, hãy liên hệ hỗ trợ với `ref` nếu có.

Xử lý Lỗi trong Mã

xử lý lỗi được khuyến nghị

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