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자의 16진수 문자열이 아닙니다	해시 형식을 확인하세요. 정확히 64개의 16진수 문자여야 하며 접두사는 없어야 합니다.
`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}`을(를) 서명했는지 확인하세요 (소문자 16진수 해시, 콜론, 정확한 Tron 주소).
`signature_mismatch`	403	서명자 주소가 결제 발신자와 일치하지 않습니다	서명은 TRX 결제를 전송한 동일한 지갑에서 생성되어야 합니다. 다른 지갑 = 거절됩니다.

결제 오류

오류 코드	HTTP	원인	해결 방법
`payment_verification_failed`	404 / 400	온체인 결제를 검증할 수 없습니다. `message` 필드에 구체적인 원인이 설명되어 있습니다.	일반적인 원인: 거래가 아직 확인되지 않음 (3-5초 기다렸다가 한 번 더 시도), 잘못된 수신자 주소, 거래가 TRX 전송이 아님, 최소 4 TRX 미만.
`hash_already_used`	409	이 거래 해시는 이미 청구되었습니다	각 결제 해시는 한 번만 사용할 수 있습니다. 새로운 위임을 위해 새 결제를 전송하세요.

서비스 오류

오류 코드	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);
  