コアガイド
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キーを確認してください |
413 | リクエストまたはアップロードされたファイルが大きすぎる | ドキュメント化されたモデルまたはエンドポイントの制限まで入力を削減してください |
429 | リクエスト制限に達した | Retry-After を待機してください |
500–504 | サービスの利用不可またはネットワーク障害 | retryable が true の場合のみ、retry_after と回数制限を守って再試行してください |
一般的なエラーコード
| コード | 意味 | 変更すべき点 |
|---|---|---|
invalid_api_key | API キーがない、無効、停止中、または失効している | Authorizationヘッダーとキーの値を確認してください |
expired_api_key | API キーの有効期限が切れている | 有効なキーを作成または選択してください |
insufficient_balance | アカウント残高がリクエストをカバーできない | 残高を追加、リクエストを削減、または低価格のモデルを選択してください |
quota_exceeded | APIキーが独自の制限に達した | キーの制限を増やすか、別の有効なキーを使用してください |
model_not_allowed | キーが要求されたモデルを使用できない | キーのモデルリストを更新するか、許可されたモデルを選択してください |
model_not_found | モデルIDが不明または利用不可 | /v1/models を読み取り、現在のモデルIDを使用してください |
context_length_exceeded | 入力がモデルの許容範囲を超えている | 履歴を削除するか、より大きなコンテキストウィンドウを持つモデルを選択してください |
rate_limit_exceeded | 現在のウィンドウでリクエストが多すぎる | Retry-After を待機してください |
payload_too_large | リクエストボディまたはファイルがエンドポイントの制限を超えている | 入力を削減または圧縮してください |
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 と回数制限を守って再試行してください |
| レスポンス前に接続が切断された | 場合による。作成操作の場合は、タスクや副作用が既に存在するか確認してください。 |
| 出力後にストリームが中断された | 完了したレスポンスとは見なさないでください。繰り返すと異なる出力や二重課金が発生する可能性があります。 |
画像、動画、音楽、3D、およびWorldsの作成については、タスクIDが返されたらすぐに保存してください。作成リクエストがタイムアウトした場合は、別の作成リクエストを送信する前にタスクレコードを確認してください。
Request IDの保持
レスポンスヘッダーには、追跡用のRequest IDが含まれています。エンドポイント、モデル、時刻、および独自のユーザーIDやジョブIDと共に保存してください。非同期作業の場合は、task_id および billing_transaction_id が存在する場合も保存してください。
サポートに連絡する際は、これらのIDと編集済みの例を含めてください。APIキー、管理トークン、プライベートメディア、署名付きURL、または完全なプライベートプロンプトは絶対に送信しないでください。