短い答え: 失敗したリクエストのたびに Claude から GPT へ切り替えないでください。401 は認証を修正すべきことを意味し、パス関連の 404 は URL またはエンドポイントを正す必要があることを意味します。429 または一時的な 5xx はバックオフ付きでリトライできます。上限付きのリトライでも失敗する場合は、互換性のあるフォールバックモデルに切り替えても構いません。
重要な例外が一つあります: error.code: invalid_request を伴う 500 応答は依然としてリクエスト側の問題です。これを再試行したり、同じ壊れたペイロードを別のモデルに送ったりしても、バグを隠すだけです。
この記事は 2026 年 8 月 20 日に CometAPI のエラー、リトライ、ベース URL、レート制限、モデル・フォールバックのドキュメントに照らして検証されました。本稿はエラーの分類のみを扱います。ルート設計、プロバイダーの認証情報、複数層のフェイルオーバーについては complete model fallback tutorial および technical fallback guide を参照してください。
リトライか失敗かの判断から始める
| ステータス | 通常の意味 | リトライ? | フォールバック? | 最初の対応 |
|---|---|---|---|---|
| 401 | キーが欠落/無効 | いいえ | いいえ | ベアラートークンを修正 |
| 404 | パスまたはエンドポイントが誤り | いいえ | いいえ | ベース URL とルートを確認 |
| 429 | レート制限または飽和 | はい | 上限リトライ後に検討 | ジッター付きでバックオフ |
| 500 + invalid_request | 不正整形のリクエスト | いいえ | いいえ | ペイロードを修正 |
| 500/503/504/524 | 一時的なプラットフォーム/プロバイダー障害 | はい | 上限リトライ後に検討 | リクエスト ID を保持 |
実務上の問いは「Claude が失敗したか？」ではなく「このリクエストの無効な部分を変えずに、別のモデルが成功し得るか？」です。認証とパスのエラーは接続自体に影響するため、モデルを変えても解決しません。容量やサーバーの一時障害はルート依存の可能性があるため、フォールバックが役立つ場合があります。
モデルを切り替える前にエラー本文を読む
HTTP ステータスに加えて error.code と error.message を使用してください。多くの CometAPI の失敗は次のようなラップ形式を取ります:
{
"error": {
"message": "human-readable detail and request id",
"type": "comet_api_error",
"param": "problematic_parameter_or_empty",
"code": "error_code_or_empty"
}
}
ステータスコードの先頭の桁だけで分類しないでください。500 に invalid_request が含まれる場合がありますし、誤った CometAPI パスでは、きれいな JSON の 404 ではなくリダイレクトや HTML が返ることもあります。
401 Unauthorized: 認証を停止して修正する
401 は通常、API キーが欠落、形式不正、期限切れ、または誤った環境から読み込まれていることを意味します。ヘッダーは次の通りでなければなりません:
Authorization: Bearer $COMETAPI_KEY
リトライもモデル切り替えもしないでください。どちらのルートでも同じ壊れた認証を使います。デプロイ済みサービスが古いシークレットを読み込んでいないか、キーに空白が混入していないか、意図した環境にリクエストが届いているかを確認してください。キーのローテーションや再読み込みは必ず秘密情報管理プロセスを通じて行ってください。
404 Not Found: フォールバック前に URL を修正する
OpenAI 互換リクエストでは、次のベース URL を正確に使用してください:
https://api.cometapi.com/v1
/v1 の欠落、パスセグメントの重複、誤ったエンドポイントは、404、リダイレクト、HTML レスポンス、あるいは SDK のパースエラーを引き起こすことがあります。デバッグ中は自動リダイレクト追従を無効化し、最終的なリクエストパスを API リファレンスと突き合わせて確認してください。
レスポンスにモデルが利用不能または見つからないと明示されている場合は、最新の CometAPI Models API でモデル ID を検証してください。すべての 404 をモデルの不在とみなさないでください。その正確なシグナルを捕捉し検証した後にのみ、モデル特有のフォールバックを追加してください。
429 Too Many Requests: フェイルオーバーの前にバックオフ
429 はリトライ可能です。指数バックオフにジッターを加え、バーストの同時実行数を下げ、どのルートが飽和しているかを計測してください。全ワーカーが即時リトライすると、短時間のレート制限がより大きなトラフィックスパイクに膨らみます。
小さな上限付きリトライの後で、次のモデルが同じ入力・出力契約と必要な能力をサポートしている場合にはフォールバックが適切です。フォールバックは無料ではありません。レイテンシやコスト、挙動の変化があり得るため、その使用頻度を記録してください。
5xx エラー: コードを確認し、次にリトライ
500、503、504、524 は、プラットフォーム、プロバイダー、あるいはタイムアウト種別の障害を表すことが一般的です。リクエスト ID、エンドポイント、モデル、タイムスタンプを保持したうえで、バックオフ付きでリトライしてください。同じ一過性の失敗がリトライ予算を超えて続く場合は、次の互換ルートに移行します。
ただしまず本文を確認してください。500 に error.code: invalid_request または invalid_request_error が含まれる場合は、リクエスト本文を修正し、内容が変わってからのみ再試行してください。よくある原因には、messages フィールドの欠落や、選択したエンドポイントが受け付けないプロバイダー特有のパラメータがあります。
コードで小さなポリシーを一つだけ持つ
この Python 例は、リトライとフォールバックをアプリケーション内で完結させます。1 つの CometAPI キー、OpenAI 互換のベース URL、環境変数に設定した現在の Claude および GPT のモデル ID を使用します。一過性の失敗のみをリトライし、リトライ予算を使い切った後にモデルを切り替えます。
import os, random, time
from openai import APIError, OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}
def complete(messages):
for model in MODELS:
for attempt in range(3):
try:
response = client.chat.completions.create(model=model, messages=messages)
return response.choices[0].message.content
except APIError as error:
status = getattr(error, "status_code", None)
code = getattr(error, "code", None)
if status in {401, 404} or code in {
"invalid_request", "invalid_request_error"
}:
raise
if status not in RETRYABLE:
raise
if attempt < 2:
time.sleep(2**attempt + random.random())
continue
break
raise RuntimeError("No configured route completed.")
print(complete([{"role": "user", "content": "Summarize this ticket."}]))
SDK の自動リトライを無効化して、アプリケーション側で総リトライおよびフォールバック予算を制御します。これがないと、SDK のリトライとアプリ側のリトライが掛け算になり、呼び出し回数が増え、最終応答が遅延します。
推測せずにポリシーをテストする
| 模擬シグナル | 期待される結果 | 起きてはならないこと |
|---|---|---|
| 401 | 直ちに例外を送出 | リトライも GPT 呼び出しもなし |
| 404 | 直ちに例外を送出 | 不正なパスを隠すフォールバック |
| 429 | バックオフ後にフォールバック | 即時リトライの嵐 |
| 500 + invalid_request | 直ちに例外を送出 | 壊れたリクエストの重複送信 |
| 503/504/524 | バックオフ後にフォールバック | 無制限のルート連鎖 |
これらはポリシーのテストであり、実運用のプロバイダー信頼性についての主張ではありません。ステージングでは、ステータスとエラー本文を分類器に注入し、呼び出しの回数と順序を検証し、最終的なエラーに元のリクエスト文脈が含まれていることを確認してください。
Claude から GPT へのフォールバックが安全な場合
モデルファミリーの切り替えが安全なのは、両方のルートが同じアプリケーション契約を満たせる場合に限られます。リクエストとレスポンスのフィールドを正規化し、構造化出力やツール動作を両モデルでテストし、必要な画像・ドキュメント・コンテキスト・推論能力が満たされることを確認してからルートを有効化してください。
フォールバックは副作用にも配慮するべきです。最初のルートがすでにツールを起動した、データを書き込んだ、または部分的なストリーム応答を送った場合、リクエスト全体を盲目的に繰り返すと、操作の重複やユーザーの混乱を招く恐れがあります。チェックポイントから再開するか、制御された失敗を返してください。
リトライを上限内に保つ本番チェック
- 一つの総レイテンシ予算を設定する。すべてのリトライとフォールバックを同じ締切にカウントする。
- リトライ回数に上限を設ける。ジッター付きバックオフを用い、小さな設定値で停止する。
- 同時実行を制御する。アプリケーションから出る前にバーストを抑える。
- サーキットブレーカーを追加する。繰り返し失敗するルートへの呼び出しを一時停止する。
- 意思決定をログに残す。ステータス、エラーコード、リクエスト ID、モデル、試行回数、遅延、フォールバック理由を秘密情報を保存せずに記録する。
- フォールバック率を追跡する。持続的な増加は運用上のシグナルであり、通常の成功指標ではない。
よくある質問
401 でモデルのフォールバックをトリガーすべきですか？
いいえ。API キーを修正または再読み込みしてください。同じ無効な認証で呼び出す別のモデルでも同様に失敗します。
404 はフォールバックをトリガーすべきですか？
既定ではすべきではありません。まずベース URL またはエンドポイントを修正してください。モデルが利用不能であるという別途検証済みのシグナルのみをフォールバックの分類器に入れてください。
429 は何回リトライすべきですか？
ユーザー向けレイテンシ予算に収まる小さなアプリケーション定義の上限を使用してください。ジッター付きでバックオフし、同時実行を減らし、即時かつ無制限のリトライは避けてください。
すべての 5xx はリトライできますか？
いいえ。一時的な 500、503、504、524 はリトライ候補ですが、500 で invalid_request の場合は、ペイロードを修正するまでハードフェイルにすべきです。
Claude と GPT は同じリクエストをそのまま使えますか？
アプリケーションでテスト済みの共有フィールドに限ります。プロバイダー固有のパラメータ、ツール形式、構造化出力、マルチモーダル入力にはアダプタが必要な場合があります。モデル ID を変えるだけでは互換性は証明されません。
完全なフォールバック実装はどこにありますか？
広範なアーキテクチャは How to Build Robust LLM Model Fallback Strategies を、実装詳細は CometAPI model fallback guide を参照してください。
エラー分類器をゲートキーパーにする
自動フォールバックは、狭く観測可能であるときに有用です。認証、パス、そして不正なリクエストは大きな音を立てて失敗させてください。レート制限と一時的なサーバー障害はバックオフ付きでリトライし、リトライ予算を使い切った後にのみ互換ルートへ移動します。このポリシーにより、フォールバックは構成バグを隠す手段ではなく、信頼性管理の手段になります。