エラー処理

統合エラー応答フォーマット

すべての API エラーは、統一された JSON 形式を返します。

JSON

{
  "code": 2010,
  "message": "Insufficient credits",
  "suggestion": "Please top up your account at https://platform.tripo3d.ai",
  "request_id": "req_abc123"}

フィールド	種類	説明
code	整数	エラーコード
message	文字列	エラーの説明
suggestion	文字列	提案された修正
request_id	文字列	トラブルシューティング用の一意のリクエスト識別子

HTTP ステータスコード

ステータスコード	意味	説明
200	成功	リクエストは正常に処理されました
400	無効なパラメータ	必須パラメータが欠落しているか形式が不正です
401	未認証	API Key が見つからないか無効です
403	権限が不十分です	リソースにアクセスする権限がないか、クレジットが不十分です
404	リソースが見つかりません	要求されたタスクまたはリソースは存在しません
429	リクエストが多すぎます	レート制限を超えました。リクエストの頻度を減らす
500	サービスエラー	内部サーバーエラー。後でもう一度試してください

エラーコードリファレンス

エラーコード	意味	推奨取り扱い方法
1000	無効なAPI Key	API Keyが正しいか削除されているかを確認してください
1001	無許可	リクエストヘッダーに`Authorization`が含まれているかどうかを確認する
2000	レート制限を超えました	リクエストの頻度を減らし、指数バックオフを使用した再試行を実装します。
2002	サポートされていないリクエストパラメータです	リクエスト本文のフィールド名と値がドキュメントと一致するかどうかを確認する
2003	空の入力ファイル	アップロードされたファイルが空ではなく、有効な形式を使用していることを確認します
2004	サポートされていないファイル形式です	ファイル形式がサポートされているリストにあるかどうかを確認します
2008	コンテンツポリシー違反	入力内容を修正して禁止ワードや禁止画像を避ける
2010	クレジットが不十分です	コンソールでクレジットを補充する
2015	非推奨のバージョン	最新のAPIバージョンにアップグレードしてください
2018	モデルが複雑すぎる	入力モデルの複雑さまたはポリ数を削減します。

エラー処理の例

import time
import requests

def call_api_with_retry(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        if payload:
            response = requests.post(url, headers=headers, json=payload)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limit triggered. Retrying in {wait} seconds...")
            time.sleep(wait)
            continue

        error = response.json()
        raise Exception(
            f"API error [{error['code']}]: {error['message']} "
            f"(suggestion: {error.get('suggestion', 'none')})"
        )

    raise Exception("Maximum retry attempts exhausted")

async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const wait = 2 ** attempt * 1000;
      console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, wait));
      continue;
    }

    const error = await response.json();
    throw new Error(
      `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})`
    );
  }

  throw new Error("Maximum retry attempts exhausted");
}

再試行戦略の推奨事項

429 のレート制限や 500 のサービスエラーなど、再試行可能なエラーの場合は、指数バックオフ戦略を使用します。

最初の再試行: 1 秒待ちます
2 回目の再試行: 2 秒待ちます
3 回目の再試行: 4 秒待ちます
最大再試行回数を 5 回以下に保つ

400、401、403 などの再試行不可能なエラーの場合は、例外を直接スローし、根本的な問題を修正します。

エラー処理

エラー処理

統合エラー応答フォーマット

HTTP ステータス コード

エラーコードリファレンス

エラー処理の例

再試行戦略の推奨事項

HTTP ステータスコード