오류 코드 - API 문서

오류 응답 형식

모든 오류 응답은 통일된 형식을 사용합니다:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "사람이 읽을 수 있는 오류 메시지",
    "details": "추가 컨텍스트 (선택적)"
  }
}

💡 error.code를 안정적인 분기 조건으로 사용하세요 (message는 변경될 수 있음)

HTTP 상태 코드

200 OK

요청 성공

200

201 Created

리소스 생성 성공

201

400 Bad Request

요청 매개변수가 유효하지 않습니다

400

{
  "code": "INVALID_REQUEST",
  "message": "유효하지 않은 요청 형식"
}

401 Unauthorized

인증되지 않았거나 API 키가 유효하지 않습니다

401

{
  "code": "UNAUTHORIZED",
  "message": "유효하지 않거나 만료된 API 키"
}

403 Forbidden

계정 잔액 또는 권한이 부족합니다

403

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "계정 잔액이 부족합니다"
}

404 Not Found

리소스를 찾을 수 없습니다

404

{
  "code": "ORDER_NOT_FOUND",
  "message": "주문을 찾을 수 없습니다"
}

409 Conflict

리소스 충돌

409

{
  "code": "ADDRESS_EXISTS",
  "message": "주소가 이미 존재합니다"
}

429 Too Many Requests

API 키 요청 속도 제한 초과

429

{
  "code": "RATE_LIMITED",
  "message": "속도 제한 초과"
}

500 Internal Server Error

내부 서버 오류

500

{
  "code": "INTERNAL_ERROR",
  "message": "예기치 않은 오류가 발생했습니다"
}

503 Service Unavailable

서비스 일시적으로 사용 불가 (유지보수 중)

503

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "서비스를 일시적으로 사용할 수 없습니다"
}

일반적인 오류 코드

Error Code	Status	Description	Solution
UNAUTHORIZED	401	API 키가 유효하지 않거나, 만료되었거나, 폐기되었습니다	API 키가 올바른지 확인하고, 필요 시 새로 생성하세요
INSUFFICIENT_BALANCE	403	계정 잔액이 부족합니다	계정 잔액을 충전하세요
INVALID_ADDRESS	400	TRON 주소 형식이 유효하지 않습니다	주소가 유효한 TRON 주소인지 확인하세요 (T로 시작)
INVALID_ENERGY_AMOUNT	400	에너지 수량이 유효하지 않습니다	에너지 수량은 양의 정수여야 하며, USDT 전송 시 65000 권장
INVALID_DURATION	400	대여 기간이 유효하지 않습니다	유효한 기간을 사용하세요: 1H, 1D, 3D, 7D, 14D, 30D
ORDER_NOT_FOUND	404	주문이 존재하지 않습니다	주문 ID가 올바른지 확인하세요
ADDRESS_EXISTS	409	주소가 이미 존재합니다	주소가 이미 추가되었는지 확인하거나 기존 주소를 사용하세요
RATE_LIMITED	429	API 키 요청 속도 제한 초과 (현재 POST /v1/wallet/recharges에만 적용)	지수 백오프 재시도를 구현하거나 호출 빈도를 줄이세요

처리 방법

Error	Handling
401 UNAUTHORIZED	API 키 확인/교체
403 INSUFFICIENT_BALANCE	충전 또는 요청 금액 감소
409 ADDRESS_EXISTS	조회/멱등성 처리로 전환
429 RATE_LIMITED	백오프 재시도 (Retry-After 있으면 따르고, 없으면 지수 백오프)
5xx	재시도 + 요청 컨텍스트 로깅

재시도 가이드라인

• 최대 재시도: 3회
• 백오프: 지수 (1초, 2초, 4초...)
• 429/5xx만 재시도
• 4xx는 재시도하지 않음 (클라이언트 오류)

오류 코드 및 처리