エラーコード - APIドキュメント

エラーレスポンス形式

すべてのエラーレスポンスは統一された形式を使用します:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "人間が読めるエラーメッセージ",
    "details": "追加のコンテキスト(オプション)"
  }
}

💡 error.codeを安定した分岐条件として使用してください(messageは変更される可能性があります)

HTTPステータスコード

200 OK

リクエスト成功

200

201 作成成功

リソースが正常に作成されました

201

400 不正なリクエスト

リクエストパラメータが無効です

400

{
  "code": "INVALID_REQUEST",
  "message": "無効なリクエスト形式"
}

401 未認証

未認証または無効なAPIキー

401

{
  "code": "UNAUTHORIZED",
  "message": "無効または期限切れのAPIキー"
}

403 禁止

アカウント残高または権限が不足しています

403

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "アカウント残高が不足しています"
}

404 未検出

リソースが見つかりません

404

{
  "code": "ORDER_NOT_FOUND",
  "message": "注文が見つかりません"
}

409 競合

リソースの競合

409

{
  "code": "ADDRESS_EXISTS",
  "message": "アドレスは既に存在します"
}

429 リクエスト過多

APIキーのリクエストレート制限を超えました

429

{
  "code": "RATE_LIMITED",
  "message": "レート制限を超えました"
}

500 内部サーバーエラー

内部サーバーエラー

500

{
  "code": "INTERNAL_ERROR",
  "message": "予期しないエラーが発生しました"
}

503 サービス利用不可

サービスが一時的に利用できません(メンテナンス中)

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(クライアントエラー)はリトライしない

エラーコードと対処