# TRONow — エラーと対処

この表は HMAC 加盟店 API（/openapi/v1）専用です。コンソールと管理機能は別の認証・エラー仕様を使用します。加盟店は API 認証情報で決まり、他のアカウントは指定できません。

HTTP ステータスはリクエスト結果、code はプログラムの分岐、message は人向けの説明です。

API エラーは実際の HTTP 4xx/5xx と {code, message, request_id} を返します。X-Request-ID は request_id と一致し、エラー時に data はありません。message は変更される可能性のある安全な英語説明です。分岐判定に使用しないでください。

全 API キーとサービスインスタンスで加盟店ごとの 1 秒スライディングウィンドウを共有します。初期値は認証済み API 毎秒 50 件、注文送信毎秒 10 件で、プラットフォームが変更できます。POST /orders・/address-activations は再試行も両方の枠を消費し、読み取りは API 枠のみです。X-RateLimit-Limit/Remaining・X-OrderRateLimit-Limit/Remaining は現時点の値で、予約枠ではありません。HTTP 429 RATE_LIMITED は Retry-After（秒）と X-RateLimit-Scope（requests/orders）を返します。HTTP 503 RATE_LIMIT_UNAVAILABLE は業務処理前に拒否します。受理済み注文は非同期処理を継続し、上流の制限を加盟店の HTTP 429 と混同しません。

POST の結果が不明なら client_order_id / client_activation_id で先に照会してください。タイムアウトや 5xx は未実行を意味しません。元の ID・本文・Idempotency-Key を維持し、時刻・nonce・署名を更新して同じリクエストのみを再試行してください。別の有料注文を無条件に作成しないでください。

ゲートウェイやネットワークは 429/502/504、HTML、または無応答になる場合があります。すべての失敗を JSON と仮定せず、Retry-After・回数制限付きバックオフ・request_id 記録を使用してください。HTTP_ERROR / INVALID_RESPONSE はクライアントのフォールバックで、API 業務コードではありません。未知の新コードも安全に処理し、元の HTTP ステータスと code を記録してください。

```http
HTTP/1.1 422 Unprocessable Entity
X-Request-ID: req_example
Content-Type: application/json

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Available merchant balance is insufficient.",
  "request_id": "req_example"
}
```

## リクエストエラー

| エラーコード | HTTP | 意味 | 対処方法 |
| --- | --- | --- | --- |
| INVALID_ARGUMENT | 400 | 必須パラメータが不足、または不正です。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_JSON | 400 | 本文は既知のフィールドのみを含む単一の JSON オブジェクトにしてください。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_REQUEST_BODY | 400 | リクエスト本文を完全に読み取れませんでした。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_IDEMPOTENCY_KEY | 400 | Idempotency-Key は空白を含まない可視 ASCII 文字 8〜128 文字です。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_CLIENT_ORDER_ID | 400 | client_order_id は空白を含まない可視 ASCII 文字 1〜64 文字です。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_CLIENT_ACTIVATION_ID | 400 | client_activation_id は空白を含まない可視 ASCII 文字 1〜64 文字です。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_ORDER_ID | 400 | order_id は有効なプラットフォーム注文 ID ではありません。 | 同じ加盟店に返された ID を使用し、顧客側 ID とプラットフォーム ID を区別してください。 |
| INVALID_ACTIVATION_ID | 400 | activation_id は有効なプラットフォーム有効化 ID ではありません。 | 同じ加盟店に返された ID を使用し、顧客側 ID とプラットフォーム ID を区別してください。 |
| INVALID_RESOURCE_TYPE | 400 | resource_type が不正です。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_RESOURCE_AMOUNT | 400 | resource_amount は 65000 Energy（65K）以上、対応範囲内の整数を指定してください。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_DURATION | 400 | duration が不正です。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_RECEIVER_ADDRESS | 400 | receiver_address は有効な TRON メインネットアドレスにしてください。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_ACTIVATION_ADDRESS | 400 | address は有効な TRON メインネットアドレスにしてください。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| REQUEST_TOO_LARGE | 413 | リクエスト本文が 1 MiB を超えています。 | 仕様に従って修正後に再送してください。4xx を繰り返し再試行しないでください。 |
| INVALID_CREDENTIALS | 401 | 認証ヘッダーまたは API 認証情報が不足、無効、無効化済み、または期限切れです。 | キー、シークレット、必須ヘッダー、有効期限を確認し、認証情報はサーバー側に保管してください。 |
| INVALID_SIGNATURE | 401 | HMAC 署名の検証に失敗しました。 | HTTP メソッド、パス、正規化クエリ、本文の正確なバイト列、シークレットを確認してください。 |
| TIMESTAMP_EXPIRED | 401 | X-Timestamp が不正、または許容時間範囲外です。 | サーバー時刻を同期し、ミリ秒のタイムスタンプ、nonce、署名を再生成してください。 |
| NONCE_REPLAYED | 401 | この加盟店では同じ nonce が使用済みです。 | 結果不明の注文は先に照会してください。HTTP 試行ごとに nonce と署名を更新し、再試行では業務 ID・本文・冪等キーを維持してください。 |
| IP_NOT_ALLOWED | 403 | リクエスト元 IP が認証情報の許可リストにありません。 | アプリケーションサーバーの実際の外向きパブリック IP を許可してください。 |
| INITIAL_DEPOSIT_REQUIRED | 403 | API 利用に必要な累計入金 20 TRX の条件を満たしていません。 | 累計入金が 20 TRX に達し、API が有効になってから再試行してください。 |
| ORDER_NOT_FOUND | 404 | 認証中の加盟店アカウントに注文が見つかりません。 | 同じ加盟店に返された ID を使用し、顧客側 ID とプラットフォーム ID を区別してください。 |
| ACTIVATION_NOT_FOUND | 404 | 認証中の加盟店アカウントに有効化リクエストが見つかりません。 | 同じ加盟店に返された ID を使用し、顧客側 ID とプラットフォーム ID を区別してください。 |
| ENDPOINT_NOT_FOUND | 404 | 指定の API エンドポイントは存在しません。 | Base URL と仕様の /openapi/v1 パスを確認してください。 |
| METHOD_NOT_ALLOWED | 405 | このエンドポイントは指定の HTTP メソッドに対応していません。 | 仕様のメソッドを使用してください。Allow ヘッダーに許可メソッドが示されます。 |
| IDEMPOTENCY_CONFLICT | 409 | Idempotency-Key は異なるリクエスト内容に使用済みです。 | 元の業務 ID で照会してください。競合の回避や結果不明の支払い再試行のために ID を変更しないでください。 |
| CLIENT_ORDER_ID_CONFLICT | 409 | client_order_id は異なる注文に使用済みです。 | 元の業務 ID で照会してください。競合の回避や結果不明の支払い再試行のために ID を変更しないでください。 |
| CLIENT_ACTIVATION_ID_CONFLICT | 409 | client_activation_id は異なる有効化リクエストに使用済みです。 | 元の業務 ID で照会してください。競合の回避や結果不明の支払い再試行のために ID を変更しないでください。 |
| INSUFFICIENT_BALANCE | 422 | 加盟店の利用可能残高が不足しています。 | 利用可能残高を補充し、予約済み資金を確認してから再送してください。 |
| UNSUPPORTED_PRODUCT | 422 | 指定の商品または Energy 数量は対応していません。最低注文数量は 65000 Energy（65K）です。数量を確認し、期間には 1h を指定してください。 | resource_type、resource_amount、duration をアカウントで利用可能な商品と照合してください。 |
| PRICE_UNAVAILABLE | 503 | リアルタイム見積もりを一時的に取得できません。 | Retry-After と回数制限付きバックオフを使用してください。POST の結果不明時は業務 ID で先に照会し、同一本文・冪等キーでのみ再試行してください。 |
| ADDRESS_ACTIVATION_UNAVAILABLE | 503 | アドレス有効化サービスを一時的に利用できません。 | Retry-After と回数制限付きバックオフを使用してください。POST の結果不明時は業務 ID で先に照会し、同一本文・冪等キーでのみ再試行してください。 |
| AUTH_UNAVAILABLE | 503 | 認証サービスを一時的に利用できません。キーが無効という意味ではありません。 | Retry-After と回数制限付きバックオフを使用してください。POST の結果不明時は業務 ID で先に照会し、同一本文・冪等キーでのみ再試行してください。 |
| BALANCE_OVERFLOW | 500 | 残高を一時的に取得できません。 | request_id を添えてサポートに連絡してください。取得失敗を残高ゼロと扱わないでください。 |
| INTERNAL_ERROR | 500 | サーバー内部エラーが発生しました。 | Retry-After がある場合は従い、ない場合は回数制限付きバックオフを使用してください。POST の結果不明時は業務 ID で先に照会し、同一本文・冪等キーでのみ再試行してください。 |
| RATE_LIMITED | 429 | 加盟店の API または注文送信の上限を超えました。この試行は業務処理に進んでいません。 | Retry-After 秒以上待ち、ランダムな遅延と回数上限を設けて再試行してください。timestamp・nonce・署名を更新し、業務 ID・本文・冪等キーを維持します。それ以前の結果不明の試行は先に照会してください。 |
| RATE_LIMIT_UNAVAILABLE | 503 | レート制限サービスが一時的に利用できません。この試行は業務処理に進んでいません。 | Retry-After 秒以上待ち、ランダムな遅延と回数上限を設けて再試行してください。timestamp・nonce・署名を更新し、業務 ID・本文・冪等キーを維持します。それ以前の結果不明の試行は先に照会してください。 |

## 非同期提供結果

HTTP 201 は受付を示し、提供完了ではありません。冪等リプレイは 200 です。data.status=FAILED でも照会は HTTP 200・code=OK を返します。PROCESSING は公開 txid がまだなく、資金を予約中です。CONFIRMING は txid を取得済みですが、TRON 上ではまだ確認できません。SUCCESS は取引を確認して決済済みです。FAILED は予約解除済みで、未確認 txid を証跡として保持する場合があります。REVIEWING は結果が未確定で、自動復旧や手動確認が続いており、資金は予約されたままです。failure_code は安定した理由です。

| エラーコード | 対象操作 | 意味 | 対処方法 |
| --- | --- | --- | --- |
| NO_AVAILABLE_ROUTE | エネルギー注文 | 利用可能な提供リソースがありません。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |
| DELIVERY_REJECTED | エネルギー注文 | 提供リクエストは受け付けられませんでした。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |
| CHAIN_TRANSACTION_NOT_FOUND | エネルギー注文 | 照合の結果、該当取引が TRON に記録されていないことを確認し、予約資金を解放しました。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |
| DELIVERY_FAILED | エネルギー注文 | 注文の提供に失敗しました。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |
| DELIVERY_REVIEW_REQUIRED | エネルギー注文 | 提供結果の手動確認が必要です。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |
| ON_CHAIN_FAILED | アドレス有効化 | アドレス有効化トランザクションがオンチェーンで失敗しました。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |
| BROADCAST_REJECTED | アドレス有効化 | アドレス有効化トランザクションが拒否されました。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |
| ACTIVATION_FAILED | アドレス有効化 | アドレス有効化に失敗しました。 | status を基準にしてください。SUCCESS は決済済み、FAILED は予約解除済み、REVIEWING は予約継続中です。結果確定まで元の処理を照会し、新たな有料リクエストを送らないでください。 |