コアガイド

エージェントが対応可能なエラー

プロース(散文)を解析することなく、エラーコード、再試行タイミング、モデルの提案を利用する

このページでは、アプリケーションやコーディングエージェント向けの機械可読なパブリックAPIエラーについて説明します。ワークスペースのリクエスト調査やサポートへのアクセス権を付与するものではありません。ワークスペース内のリクエストについては、まずリクエストのトラブルシューティングを参照してください。

OpenAI互換のTokenLabエラーには、エージェントやアプリケーション向けの構造化されたヒントが含まれる場合があります。これらのフィールドが存在する場合はそれを使用し、人間が読むための message を解析して動作を決定しないでください。

Anthropic MessagesおよびGemini APIは独自のネイティブなエラー形式を維持しているため、このページの拡張機能はOpenAI互換のChat CompletionsおよびResponsesエラーにのみ適用されます。

オプションのエラーフィールド

以下のすべてのフィールドは error オブジェクト内に表示され、存在しない場合もあります。

フィールド型用途
did_you_meanstring提供終了したモデルの代替、または最も近い利用可能なモデルID
suggestionsarrayリクエストに適している可能性のあるモデル
hintstring短い説明や推奨されるアクション
retryableboolean同じリクエストが後で成功する可能性があるかどうか
retry_afternumber再試行までの待機時間(秒)
balance_usdnumber現在の残高(USD)
estimated_cost_usdnumber拒否されたリクエストの推定コスト(USD)
top_up_urlstring一部の insufficient_balance エラー時に表示される課金ページへのリンク
min_top_up_usdnumber一部の insufficient_balance エラー時に表示される最小チャージ額(USD)

クライアントは、引き続きHTTPステータスと code によってすべてのエラーを処理する必要があります。これらの追加フィールドは、必須フィールドではなく、有用なコンテキストとして扱ってください。

不明なモデル

スペルミスや利用不可能なモデルを指定すると 400 model_not_found が返されます。did_you_mean が存在する場合は、それをユーザーに表示するか、または選択されたモデルを変更する権限がすでに製品にある場合にのみ再試行してください。

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.6-terra",
    "suggestions": [
      {"id": "gpt-5.6-terra"},
      {"id": "gpt-5.6-luna"}
    ],
    "hint": "Did you mean 'gpt-5.6-terra'? Use GET /v1/models to list all available models."
  }
}

残高不足

402 insufficient_balance には、現在の残高と必要な推定額、またはチャージ用リンクと最小チャージ額が含まれる場合があります。アプリケーションは、チャージ用リンクの提示、より安価なモデルへの変更、またはリクエストの縮小を行うことができます。

{
  "error": {
    "message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "retryable": false,
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v4.1-flash"}
    ],
    "hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

モデル利用不可

503 all_channels_failed または 503 delivery_tier_unavailable は、必ずしも一時的な停止を意味するわけではありません。リクエストされた操作が選択されたDeliveryティアで提供されていない場合、retryable は false となり、retry_after は省略されます。同じリクエストを繰り返さないでください。別のモデルを選択する前に、GET /v1/models で操作とDeliveryの可用性を確認してください。名前が似ているからといって可用性が保証されるわけではありません。検証されていない代替案は省略されます。

{
  "error": {
    "message": "This model is unavailable for the requested operation and Delivery tier.",
    "type": "all_channels_failed",
    "code": "all_channels_failed",
    "retryable": false,
    "hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
  }
}

レート制限

429 rate_limit_exceeded の場合は、retry_after 秒待機するか、標準の Retry-After レスポンスヘッダーを使用してください。

{
  "error": {
    "message": "Rate limit exceeded (1000/min for user role). Please retry later.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

コンテキストが長すぎます

400 context_length_exceeded は、同じリクエストを再送しても解決しません。入力を短縮するか、より大きなコンテキストウィンドウを持つモデルをユーザーに選択させてください。

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

正しいAPI形式を見つける

モデル固有のAPIを使用する前に、GET /v1/models/{model} から tokenlab.accepted_request_formats を読み取ってください。

値エンドポイント
openai_chat_completions/v1/chat/completions
openai_responses/v1/responses
anthropic_messages/v1/messages
gemini_generate_content/v1beta/models/{model}:generateContent

受け入れられた形式によってエンドポイントが確定します。個々のツールやフィールドはモデルによって異なる場合があるため、依存する前にモデルページを確認してください。

タスク別にモデルを探す

Models APIは、チャット以外のタスクに対する現在の推奨リストを返すことができます:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

有効な recommended_for の値は、image、video、music、3d、tts、stt、embedding、rerank、translation、decision です。選択したモデルIDを作成リクエストで明示的に送信してください。TokenLabが勝手に別のモデルに置き換えることはありません。

機械可読な概要

エージェントは、以下の場所でコンパクトなAPI概要を読み取ることができます:

GET https://api.tokenlab.sh/llms.txt

これには、最初のリクエスト、一般的なエンドポイント、モデルフィルター、エラーハンドリングのガイダンスが含まれています。

リクエストを再送せずにエラーを処理する

この例では、1回のリクエストを行い、選択されたモデルを保持し、構造化された復旧情報を報告します。SDKの再試行は無効化されているため、アプリケーション側で再試行が安全かどうかを判断できます。モデルの提案を提示して明示的な選択を促してください。受け入れられた生成やタイムアウトした生成を自動的に再送しないでください。タイムアウトしたリクエストを安全に再試行するには、べき等キーによる安全な再試行で示されているように、Idempotency-Key を付けて送信してください。

import os
from openai import OpenAI, APIStatusError

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    try:
        response = client.chat.completions.create(
            model="gpt-5.6-terra",
            messages=[{"role": "user", "content": "Reply only with OK."}],
        )
        print(response.choices[0].message.content)
    except APIStatusError as exc:
        body = exc.body if isinstance(exc.body, dict) else {}
        error = body.get("error", body)
        if not isinstance(error, dict):
            error = {}
        print({
            "status": exc.status_code,
            "request_id": exc.request_id,
            "code": error.get("code"),
            "hint": error.get("hint"),
            "suggested_model": error.get("did_you_mean"),
            "retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
        })
        raise

このページの内容