Claude Codeの429は2種類ある——usage枠とthroughput制限を取り違えた代償

Claude Codeで「API Error (429)」が出たとき、まず確認すべき質問は「この429、原因は何なのか」だ。実は2系統まったく違う制限が、同じエラー番号で報告される。分単位で回復するthroughput制限（速度の上限）と、5時間窓や週次で管理されるusage枠（総量の上限）。両者は看板が同じなのに、対処法が正反対という厄介さがある。throughputなら「待つか遅くすればいい」が、usageなら「待っても無駄、総量を減らすしかない」。ここを取り違えると、subagentを並列実行するたびに両方を踏む羽目になる。

AIの鬼が引っかかるのはここだ。エラーメッセージが区別を示さないのに、APIドキュメントでは「こっちが本当の上限」みたいな顔で2つを並べて説明している。実装者には「どっちにぶつかったのか」を自分で推理させるしかない。しかも推理を誤ると、無駄な待機時間か無駄なリトライで時間を溶かす。実測では、75体のfan-outで両方を同時に踏んだ後、「throughputだけ対策すればいい」という初歩的な誤解をしていた期間が3日あった。その3日は、実は総量を減らす設計への転換をすべき期間だったのだ。

ifが分かれるのは、「/usage」コマンドで使用率とリセット時刻を見られるかどうか。タンク（usage）が満杯なのに蛇口の開け方（throughput）ばかり工夫する奴隷労働を避けるには、これが唯一の手がかりだ。中小企業でAIツールを常用している現場なら、「429が出た→焦らず/usageを見て、リセット時刻が表示されているか確認する」をチェックリストに入れるだけで、ムダな対応をぐっと減らせる。