コアガイド
APIエラーの処理
エラーコードの読み取り、適切な再試行、およびRequest IDの保持について
HTTPステータスと code に基づいてエラーを処理してください。message は人間が読むためのものであり、予告なく変更される可能性があります。
Chat CompletionsおよびResponsesは、OpenAI形式の error オブジェクトを使用します。Anthropic MessagesおよびGeminiは独自の形式を維持しているため、すべてのTokenLab APIに対して単一のパーサーを使用しないでください。
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}TokenLabが作成するOpenAI互換エラーには、常に message と type が含まれます。その他のフィールドは、関連がある場合にのみ表示されます。
ステータスコード
| ステータス | 意味 | 推奨されるアクション |
|---|---|---|
400 | フィールド、モデルID、または入力が無効 | リクエストを修正してください。変更せずに繰り返さないでください |
401 | APIキーが欠落、無効、期限切れ、または取り消されています | キーを置き換えてください |
402 | 残高またはAPIキーの制限が不足しています | チャージ、制限の引き上げ、またはリクエストの削減を行ってください |
403 | このキーではリソースやモデルを使用できないか、アカウントが制限されています | キーの権限やモデルを変更するか、サポートに連絡してください |
404 | リソースが存在しないか、利用できません | IDおよび作成に使用したAPIキーを確認してください |
409 | Idempotency-Key が既に使用されています(異なるリクエストボディでの使用 idempotency_conflict、またはTokenLabが結果を返せないリクエストでの使用 idempotency_replay_unavailable, idempotent_response_not_replayable)。TokenLabはリクエストを再実行していません | 新しいリクエストには新しいキーを使用してください。同じキーで再試行するかどうかの判断については、べき等キーを使用した安全な再試行を参照してください |
413 | リクエストまたはアップロードされたファイルが大きすぎます | ドキュメントに記載されているモデルまたはエンドポイントの制限まで入力を削減してください |
429 | リクエスト制限に達しました | Retry-After を待機してください |
500–504 | サービス利用不可またはネットワーク障害 | retryable が true の場合のみ再試行してください。retry_after を尊重し、試行回数を制限してください |
一般的なエラーコード
| コード | 意味 | 変更すべき点 |
|---|---|---|
invalid_api_key | APIキーが欠落、無効、非アクティブ、または取り消されています | Authorizationヘッダーとキーの値を確認してください |
expired_api_key | キーの有効期限が切れています | アクティブなキーを作成または選択してください |
insufficient_balance | アカウント残高がリクエストをカバーできません | 残高を追加、リクエストを削減、または低価格のモデルを選択してください |
quota_exceeded | APIキーが独自の制限に達しました | キーの制限を増やすか、別の有効なキーを使用してください |
model_not_allowed | キーが要求されたモデルを使用できません | キーのモデルリストを更新するか、許可されたモデルを選択してください |
user_suspended, account_restricted | HTTP 403。アカウントがAPIを使用できません | Request IDを添えてサポートに連絡してください |
invalid_delivery_policy | HTTP 400。X-TokenLab-Delivery-Policy ヘッダーが auto、verified、official のいずれでもありません | 3つの値のいずれかを送信するか、ヘッダーを削除してください |
model_not_found | モデルIDが不明または利用できません | /v1/models を読み取り、現在のモデルIDを使用してください |
context_length_exceeded | 入力がモデルの許容範囲を超えています | 履歴を削除するか、より大きなコンテキストウィンドウを持つモデルを選択してください |
missing_required_parameter | 必須フィールドが欠落しています。param がフィールド名を指定します(例:デフォルトモデルのない音声や画像リクエストにおける model) | param が指定するフィールドを送信してください |
invalid_value | フィールドにモデルが受け入れない値が含まれています(例:reasoning_effort の値)。メッセージに受け入れ可能な値が記載されています | 記載されている値のいずれかを使用してください |
invalid_response_format_type | HTTP 400。response_format がオブジェクトであるのに使用できる type がないか、このエンドポイントが受け入れない type が指定されています。param は response_format です | response_format.type を text、json_object、json_schema のいずれかに設定してください。json_schema の場合は json_schema.name と json_schema.schema も送信してください |
invalid_image_url | TokenLabが画像URLを使用できません:有効なHTTP(S) URLまたは画像データURIではないか、画像ホストが画像を返しませんでした。param がフィールド名を指定します | 公開されているHTTPS画像URLまたはサポートされているデータURIを送信してください |
unsupported_model_capability | 選択されたDeliveryティアのどのルートも、リクエストパラメータ(操作、resolution、aspect_ratio、duration、入力メディアフィールド、web_search_options、max_tokens など)をサポートしていません。メッセージに一致しなかった各パラメータ名と、モデルが公開している場合はサポートされている値が記載されています | パラメータを削除または変更するか、別のDeliveryティアまたはモデルを選択してください。リクエストをそのまま繰り返さないでください |
unpriceable_selection | ビデオのリクエストに価格決定に必要なセレクターが含まれていないため、TokenLabが価格を算出できません。param がセレクター名を指定します | param が指定するフィールドを設定してください |
model_pricing_unavailable | HTTP 503。リクエストは有効ですが、TokenLabはこのリクエストが使用可能なルートで、このモデルと操作の組み合わせの価格を算出できません。リクエストは課金されておらず、retryable は false です | リクエストをそのまま繰り返さないでください。別のモデルや操作を選択するか、Request IDを添えてサポートに連絡してください |
idempotency_conflict | HTTP 409。Idempotency-Key が別のリクエストに属しています。TokenLabはこのリクエストを実行しませんでした | 新しいキーを使用して新しいリクエストを送信してください |
idempotency_replay_unavailable | HTTP 409。Idempotency-Key は既に使用されており、TokenLabは結果を返せません。TokenLabはこのリクエストを再実行しませんでした | 最初のリクエストがまだ実行中の可能性がある場合は、待機してから同じキーで再試行してください。それ以外の場合は新しいキーを送信してください。べき等キーを使用した安全な再試行を参照してください |
idempotent_response_not_replayable | HTTP 409。Idempotency-Key は既に完了した作成リクエストに属しており、TokenLabは元の作成レスポンスを返せません。レスポンスボディのトップレベルには error と並んで task_id が含まれます。TokenLabはこのリクエストを再実行しませんでした | このキーでリクエストを繰り返さないでください。新しいタスクが必要な場合のみ、新しいキーを送信してください |
rate_limit_exceeded | 現在のウィンドウでリクエストが多すぎます | Retry-After を待機してください |
all_channels_failed | 選択されたモデルはこのリクエストを処理できません | retryable が true の場合のみ再試行してください。retry_after を尊重し、試行回数を制限してください |
timeout_error | リクエストが時間内に完了しませんでした | 操作の繰り返しが安全な場合のみ再試行してください |
503 all_channels_failed または 503 delivery_tier_unavailable は、必ずしも一時的な停止を意味するわけではありません。要求された操作が選択されたDeliveryティアで提供されていない場合、retryable は false となり、retry_after は省略されます。同じリクエストを繰り返さないでください。別のモデルを選択する前に、GET /v1/models で操作とDeliveryの可用性を確認してください。名前が似ているからといって可用性が保証されるわけではありません。検証されていない代替手段は省略されています。
一部のOpenAI互換エラーには、オプションの did_you_mean、suggestions、alternatives、hint、retryable、または retry_after フィールドが含まれます。エージェントが対応可能なエラーを参照してください。
リクエストがOfficialルートで実行され、アップストリームサービス自体がリクエストを拒否した場合(受け入れられない入力やコンテンツポリシーの決定など)、エラーには upstream も含まれます。これには、報告されたアップストリームの message に加え、既知の場合は code と source(アップストリームサービス名)が含まれます。Anthropic MessagesおよびGeminiのエラーは、自身の error 内に同じオブジェクトを保持します。code と type による分岐を維持してください。upstream.code の値はアップストリームサービスによって定義されており、変更される可能性があります。
再試行の判断
| エラー | 同じリクエストを繰り返すか? |
|---|---|
400, 401, 402, 403, 404, 413 | いいえ。リクエスト、認証情報、残高、権限、または入力を変更してください。 |
429 | はい。サーバーから提供された遅延時間後に再試行してください。 |
500–504 | retryable が true の場合のみ再試行してください。retry_after を尊重し、試行回数を制限してください。 |
| レスポンス前に接続が切断 | はい。べき等キーを使用した安全な再試行にリストされており、Idempotency-Key がある場合:同じキーとボディで再送信してください。それ以外の場合は、タスクや副作用が既に存在するかどうかを最初に確認してください。 |
| 出力到着後にストリームが中断 | 完全なレスポンスとは見なさないでください。繰り返すと、異なる出力が生成されたり、2回目の課金が発生したりする可能性があります。 |
画像、ビデオ、音楽、3D、およびWorldsの作成については、タスクIDが返されたらすぐに保存してください。作成リクエストがタイムアウトした場合は、同じ Idempotency-Key とボディで再送信して元のタスクを取得してください。キーがない場合は、別の作成リクエストを送信する前にタスクレコードを確認してください。
べき等キーを使用した安全な再試行
タイムアウトや接続切断が発生した場合、TokenLabがリクエストを実行したかどうかは判断できません。以下にリストされているリクエストには Idempotency-Key ヘッダーを追加してください。これにより、同じリクエストを再試行しても、2回実行されたり課金されたりすることはありません。
- 各操作に新しい一意の値(UUIDなど)を使用してください。キーは最大255文字までです。TokenLabはこれより長いキーを無視し、その場合リクエストにはべき等保護が適用されません(再試行が実行され、再度課金されます)。
POST /v1/messages/batchesは例外で、256文字を超えるキーは400で拒否されます。 - リクエストを送信する前に、独自のジョブレコードにキーを保存してください。
- 再試行時は、同じAPIキー、同じ
Idempotency-Key、同じボディを送信してください。 idempotency_replay_unavailableを伴う409以外のレスポンスを受け取った後は、そのキーを再度使用しないでください。新しい試行は新しいキーで行ってください。- SDKの再試行を無効(
max_retries=0)にし、コード側でキーを再利用するタイミングを決定できるようにしてください。
ヘッダーがない場合、すべての再試行は新しいリクエストとして扱われます。
タスクを作成するリクエスト
これらの作成リクエストは Idempotency-Key を受け入れます:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generations,POST /v1/worlds/generations- タスクを返す場合の
POST /v1/images/generationsおよびPOST /v1/images/edits "background": trueを指定したPOST /v1/responsesPOST /v1/messages/batches
作成リクエストがタイムアウトした場合は、変更せずに再送信してください。TokenLabは元の作成リクエストの結果を返し、2つ目のタスクを作成、ディスパッチ、または課金することはありません。通常、結果は同じ id を持つ元のタスク(Responsesの場合は元のレスポンスオブジェクト)であり、ポーリングを継続できます。ビデオ、音楽、3D、Worlds、および画像のタスクの場合、結果は最初の作成リクエストが失敗した際の元のエラーになることもあります。そのようなタスクが既に完了しており、TokenLabに保存された作成レスポンスがない場合、再試行は 409 とコード idempotent_response_not_replayable を返し、レスポンスボディのトップレベルに task_id が含まれます。
TokenLabが既に受け入れたキーで異なるボディを送信した場合、TokenLabはリクエストを拒否し、タスクを作成しません。ビデオ、音楽、3D、およびWorldsの作成リクエストは、コード idempotency_conflict を伴う 409 を返します。Message Batchesはエラータイプ conflict_error を伴う 409 を返します。画像タスクおよび background: true を指定したResponsesリクエストの場合、このケースのステータスコードとエラーコードは保証されません。同じキーでリクエストを再試行しないでください。
Chat Completions、Responses、およびMessages
POST /v1/chat/completions、background を指定しない POST /v1/responses、および POST /v1/messages は、指定されたキーを持つリクエストを1回のみ実行します。同じキーでの再試行は、以下のいずれかの結果になります:
| 状況 | 結果 |
|---|---|
| 最初のリクエストがまだ実行中 | コード idempotency_replay_unavailable を伴う 409 |
| クライアントの切断後に最初のリクエストが完了。リクエストはストリーミングされておらず、結果は1MB以下であり、24時間以内に同じボディで再試行 | 元のレスポンスボディとヘッダー Idempotent-Replayed: true を伴う 200。TokenLabはリクエストを再実行または再課金しません |
| キーが他の方法で使用された(例:結果を受信済み、リクエストがストリーミングされた、結果が1MBを超えた、または24時間以上経過) | コード idempotency_replay_unavailable を伴う 409 |
| ボディが最初のリクエストと異なる | 409(通常はコード idempotency_conflict)。一部のリクエストは idempotency_replay_unavailable を返す |
いずれかのコードを伴う 409 は、TokenLabがリクエストを再実行しなかったことを意味します。キーを持つストリーミングリクエストは2回実行できませんが、TokenLabは出力を再送することはできません。
以下の例は、タイムアウトしたChat Completionsリクエストを、結果が得られるまで同じキーで再試行します:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # このキーをジョブレコードと一緒に保存してください。
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # レスポンスなし:同じキーとボディで再試行。
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# 最初の試行がまだ実行中の可能性があります。後の再試行で結果が返されます。
raise RuntimeError(f"No result for Idempotency-Key {key}")最後の試行でも idempotency_replay_unavailable が返される場合、TokenLabはその結果を返すことができません。2回目の実行と2回目の課金が許容される場合のみ、新しいキーでリクエストを送信してください。
Request IDの保持
レスポンスヘッダーには、追跡用のRequest IDが含まれています。エンドポイント、モデル、時刻、および独自のユーザーIDやジョブIDと一緒に保存してください。非同期処理の場合は、存在する場合に task_id と billing_transaction_id も保存してください。
サポートに連絡する際は、これらのIDと編集済みの例を添えてください。APIキー、管理トークン、プライベートメディア、署名付きURL、または完全なプライベートプロンプトは絶対に送信しないでください。