長時間のセッションを回していると、応答が急に overloaded_error で止まることがあります。Anthropic 側の混雑時に返る HTTP 529 で、手元のコードが正しいかどうかは関係ありません。この中断を別モデルへの自動退避で食い止める設定が fallbackModel です。
overloadedで止まるのはどこか
529 overloaded_error が返るとき
API が混雑すると、リクエストには 529 Overloaded が返ります。Claude Code のターン途中でも同じ。手元では、こんな1行で応答が切れます。
API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}対話中なら送り直せば済みます。厄介なのはターンがそこで終わる点。書きかけの編集やテスト実行の途中で切れると、続きは手動でやり直しになります。
無人実行ほど痛い
cron や GitHub Actions から claude -p で回している場合、529 が返った瞬間にジョブは失敗扱い。夜間バッチが1回の混雑で丸ごと空振りする、という事故が起きます。1回のジョブが opus 前提で20分回る想定なら、その20分がまるごと無駄。混雑は夜間や特定の時間帯に偏るので、決まった時刻に走る cron ほど当たりやすい。リトライだけでは取りこぼします。
fallbackModelを設定する
退避先はユーザー設定かプロジェクト設定の JSON に書きます。まず形から。
{
"model": "claude-opus-4-8",
"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}~/.claude/settings.json に置くとこうなります。opus-4-8 が過負荷なら sonnet-5、それも駄目なら haiku-4-5 の順で試す動きです。退避が起きると、切り替えたモデルを知らせる通知が1行。
> claude-opus-4-8 が利用できないため claude-sonnet-5 に切り替えました公式ドキュメントの “Fallback model chains” では、切り替えが効く範囲を “for the rest of the turn” と書いています。そのターンの残りだけで、次のターンは model に指定した opus-4-8 に戻ります。恒久的な変更ではありません。
退避先が埋まったら次へ進む
退避した sonnet-5 も過負荷なら、チェーンの次へ進みます。全部が埋まって初めてターンが失敗する。3モデル積んでおけば、同時に3つとも過負荷という状況までは粘れます。退避先は既定モデルと別系統にすると効きます。opus が詰まる時間帯でも sonnet は空いていることが多く、系統をずらすほど同時に全滅しにくい。
チェーンは3モデルまで
配列に並べられるのは 3個まで。4個目以降は黙って無視されます。多めに書いて保険にする、は不可。"default" と書いた要素は、その位置が既定モデルに展開されます。チームで既定モデルが変わっても、退避チェーンの記述を追従させずに済みます。
リトライで粘るか、退避するか
529 が返ったとき、Claude Code はまずリトライで粘ります。退避はその先の話。両者の守備範囲が違います。
リトライが効く範囲
一時的なネットワーク断や瞬間的なエラーは、同じモデルへの再送で通ることが多い。回数は CLAUDE_CODE_MAX_RETRIES で調整します。既定でも数回はリトライするので、瞬断ならユーザーが気づかないまま通ることもある。v2.1.199 で入った CLAUDE_CODE_RETRY_WATCHDOG は、容量起因でない一時エラーのリトライ既定を 300回まで引き上げ、15回の上限も外します。
退避が要る範囲
ただ、529 overloaded は容量起因です。混雑のピーク中は、同じモデルに投げ直しても返らないことがあります。ここでモデルを変えるのが fallbackModel の役割。同じモデルに投げ直して待つより、空いているモデルへ移るほうが早く結果が返ります。応答が5分無反応なら中断して再試行する CLAUDE_ENABLE_STREAM_WATCHDOG（v2.1.196 から既定で有効）と合わせると、応答が返らないまま止まる時間を減らせます。
–fallback-model で一時的に上書きする
設定ファイルを触らず試す
その場で試すだけなら CLI フラグが速い。
claude --fallback-model sonnet,haikuカンマ区切りで順に試します。エイリアス（opus / sonnet / haiku / fable）でも、claude-sonnet-5 のようなフルIDでも指定できます。効くのはこのセッションの間だけ。opus が落ちたら sonnet、次に haiku へ退避します。
設定ファイルより強い
--fallback-model は settings.json の fallbackModel を1セッション分だけ上書きします。v2.1.166 からは対話セッションにも効くようになりました。それ以前は -p などの非対話実行が中心。現行の v2.1.201 でも挙動は同じです。
設定ファイルをまたぐと挙動が変わる
ファイルをまたいだときの挙動が、他の配列設定と違います。大半の配列設定はユーザー設定とプロジェクト設定でマージされますが、fallbackModel はされません。マージされる設定とされない設定が混在するので、この1つだけ挙動が頭から抜けやすい。
普通の配列設定はマージされる
permissions.allow のような配列は、ユーザー設定とプロジェクト設定が足し合わされます。両方に書けば両方が効く。多くの人がこの挙動を前提に設定を組みます。
fallbackModel はマージしない
公式ドキュメントの記述はこうです。
this key does not merge across settings files: the highest-precedence file that defines it supplies the entire chain
最も優先度の高いファイルで定義されたチェーンが丸ごと採用され、他のファイルのチェーンは無視されます。足し算にはなりません。
アンチパターンから見ます。ユーザー設定に3モデル、プロジェクト設定に1モデルを書いたとします。
// ~/.claude/settings.json
{ "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5", "default"] }
// ./.claude/settings.json (プロジェクト、優先度が上)
{ "fallbackModel": ["claude-haiku-4-5"] }期待は「4モデルに増える」。実際はプロジェクト側の ["claude-haiku-4-5"] だけが使われ、ユーザー側の3モデルはまるごと消えます。opus が過負荷になった瞬間、sonnet を飛ばして haiku まで落ちます。
プロジェクトに検証用の fallbackModel を1個だけ残したまま忘れていて、ユーザー側の退避チェーンが効かず、生成物の傾向が急に変わって気づいた、という踏み方を一度しました。マージ前提で読むと原因にたどり着きにくい。
チームで共有するときの置き場所
共有したい退避チェーンは、プロジェクトの .claude/settings.json に置きます。各自のユーザー設定に別の fallbackModel が残っていても、プロジェクト側が優先で丸ごと上書き。逆に、退避先を各自に委ねたいならプロジェクト側には書かない。マージされないので、どのファイルに書くかがそのまま結論になります。優先順位は enterprise 管理設定 > CLI フラグ > プロジェクトのローカル設定 > プロジェクト設定 > ユーザー設定。退避先が意図とずれたら、上位のファイルに fallbackModel が残っていないかを先に見ます。
/model・availableModels との住み分け
/model は手で選ぶもの、fallbackModel は勝手に退避するもの。発動のタイミングが逆です。
| 設定 | 役割 | 発動 |
|---|---|---|
model / --model | 既定モデルを選ぶ | 手動 |
fallbackModel | 過負荷・不在時の退避先 | 自動 |
availableModels | 選べるモデルを制限 | 常時 |
手動と自動を取り違えない
混同すると、手動で opus を選んだつもりが、退避で haiku まで落ちていた、が起きます。出力の質が変わったら、まず退避が走っていないかを疑います。直前の通知を遡れば、どのターンから退避が始まったかを追える。1ターンだけ haiku、ということも起こります。
availableModels で縛るとき
enforceAvailableModels を有効にすると、availableModels の許可リストが既定モデルにも効きます。この状態で許可リスト外のモデルを退避先に書くと、そのモデルへは退避できません。たとえば許可リストを opus と sonnet に絞ったなら、退避先に haiku は書けない。書いても opus の過負荷時に haiku へは移れず、sonnet で止まります。許可リストと退避チェーンはセットで設計するのが前提になります。
無人実行に組み込む
cron・CIで退避先を渡す
定期実行では、フラグで退避先を渡しておくとジョブが混雑に強くなります。
claude -p "$(cat nightly-task.md)" --fallback-model sonnet,haikuこれまでは opus 固定で、混雑に当たった夜はジョブが飛んでいました。退避先を足してからは、opus が 529 を返しても sonnet で完走。退避が走った回は通知が cron のログに残るので、opus が何回落ちたかも後から数えられます。退避が成功したジョブは通常どおり exit 0 で終わります。529 でこけて非ゼロ終了する、が消えるので、後続のデプロイや通知ステップもそのまま流れる。投稿のような1日1回のジョブなら、失敗しても翌日に回せます。ただ、リリースノート生成やレビューのようにその時刻でしか意味がないジョブは、退避先を積んでおく価値が大きい。
質が変わる前提で退避先を選ぶ
haiku まで落ちると生成物の傾向が変わります。退避先は「落ちても許容できるモデル」を並べる。実務では、コードを書くジョブは ["claude-sonnet-5"] の1段だけ、要約や分類のような軽いジョブは ["claude-sonnet-5", "claude-haiku-4-5"] の2段、のようにジョブの許容ラインで分けるのが素直です。1段だけでも、opus が詰まったときに完走できるかどうかの差は大きい。コード生成が中心なら、haiku を末尾に足すより sonnet で止める判断もあります。退避したことは通知に残るので、どのモデルが出力したかは後から追えます。
まとめ
fallbackModelは過負荷（529 overloaded_error）や不在時に別モデルへ自動退避する設定。切り替えはそのターンの残りだけで、次のターンは元に戻る- チェーンは3モデルまで。
"default"は既定モデルに展開される - リトライは容量起因でないエラー向け。529 の過負荷はモデルを変える退避で乗り切る
--fallback-model sonnet,haikuは1セッション分の上書き。v2.1.166 から対話セッションでも効く- この設定はファイルをまたいでマージされない。優先度が最上位のファイルのチェーンが丸ごと採用される
enforceAvailableModelsを使うなら、退避先もavailableModelsに含める
よくある質問
Q. 退避したモデルは次のターンも続きますか。
いいえ。効くのはそのターンの残りだけで、次のターンは model に指定したモデルに戻ります。
Q. プランのレート制限（429）でも退避しますか。
退避の対象は「過負荷または不在」。混雑由来の 529 や退役モデルの指定が主な対象で、プラン上限の 429 は別枠です。