Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

Claude Code は API が予期しない非リトライエラーを返した場合、フォールバックモデルで一度だけターンを再試行するようになりました。認証・レートリミット・リクエストサイズ・トランスポートエラーは引き続き即座に表示されます。

原文（英語） ​

Claude Code now retries a turn once on the fallback model when the API rejects an unexpected non-retryable error; auth, rate-limit, request-size, and transport errors still surface immediately

概要 ​

API が予期しない非リトライエラー（500系エラーなど）を返した場合、Claude Code は設定されたフォールバックモデルで一度だけ自動的に再試行するようになりました。これにより、一時的なモデル固有の問題で作業が中断されにくくなります。ただし、認証エラー、レートリミット、リクエストサイズ超過、トランスポートエラーは引き続き即座にユーザーに表示されます。

基本的な使い方 ​

この機能は fallbackModel の設定があれば自動的に動作します。事前に settings.json か --fallback-model フラグでフォールバックモデルを設定してください：

json
{
  "model": "claude-opus-4-8",
  "fallbackModel": "claude-sonnet-4-6"
}

エラー発生時の動作：

  1. プライマリモデル（Opus 4.8）に予期しないエラー発生
  2. 自動的に Sonnet 4.6 でリトライ
  3. リトライ成功 → 作業継続
  4. リトライも失敗 → エラーを表示

実践例 ​

長時間タスクでの安定性向上 ​

複数ステップの長いタスクを実行中に一時的なエラーが発生しても、フォールバックで継続できます：

bash
claude --model claude-opus-4-8 --fallback-model claude-sonnet-4-6 \
  -p "この大規模なコードベースをリファクタリングしてください"

CI/CD での信頼性向上 ​

パイプラインでモデルエラーが発生しても自動リトライにより成功率が上がります：

bash
# フォールバックを設定してパイプラインの信頼性を向上
CLAUDE_MODEL=claude-opus-4-8 \
CLAUDE_FALLBACK_MODEL=claude-sonnet-4-6 \
claude -p "テストを実行して結果をまとめてください"

注意点 ​

  • 自動リトライは1回のみです。2回目のフォールバックへの自動リトライはありません
  • 以下のエラーは自動リトライの対象外で即座に表示されます：
    • 認証エラー（APIキーが無効など）
    • レートリミットエラー
    • リクエストサイズ超過エラー
    • ネットワーク・トランスポートエラー
  • フォールバックモデルが設定されていない場合、この機能は動作しません
  • リトライ時はフォールバックモデルを使用するため、出力品質が変わる場合があります

関連情報 ​