支出上限に当たったときの429と400

先に結論

段階の月額上限（Start $500・Build $1,000・Scale $200,000）に達すると、HTTP 429、型は rate_limit_error で、error.details.error_code は enforced_spend_limit_reached です。retry-after ヘッダーは付かず、再開は翌月1日の00:00（UTC）です。

一方、自分で下の上限を置いて当たったときはHTTP 400、型は invalid_request_error で、メッセージは「You have reached your specified API usage limits」で始まります。

3種類の停止の見分け

対処

1. 429を受けたら、まず error_code を読む。enforced_spend_limit_reached なら再試行を止める（SDK の自動再試行も失敗し続ける）
2. 段階を上げる（Console の「Request tier increase」）と、すぐ再開できる
3. 自分で置いた上限は、請求の画面で上げるか外す。上限は段階の上限を超えて置けない
4. 予防として、月の支出が上限の何割に達したかを日次で見る。これはこちらの運用の提案で、公式の機能ではない

Claude Code 用ワークスペースの上限は別に確認され、超えると retry-after 付きの429になることがあります。

具体例：月末に止まったときの切り分け

月の23日にすべての依頼が429で失敗し始めたとします。応答の本文を読むと、error_code が enforced_spend_limit_reached でした。この場合、retry-after はなく、再試行しても翌月1日（日本時間の午前9時）まで通りません。対処は、(1) 利用者への表示を「一時停止中」に切り替える、(2) 再試行のループを止める、(3) 段階の引き上げを申請する、の3つです。同じ429でも、retry-after が付いていて error_code がなければ、分あたりの枠の超過です。待てば直ります。この2つを同じ再試行の処理に入れていると、前者で無駄な再試行が続くので、分けて書いてください。

よくある取り違え

• 「429はいつも待てば直る」と読む：月額上限の429は翌月1日まで直らず、retry-after も付かない
• 「上限は自分で上げれば段階を超えられる」と読む：自分で置く上限は、段階の上限を超えられない
• 「400は入力の誤りだけ」と読む：自分で置いた支出上限に当たったときも400（invalid_request_error）が返る

この面で確かめていないこと

• 上限の近づいたときの通知機能の有無（読んでいない）
• Claude Platform on AWS の上限到達時の詳細（別の資料）

よくある質問

次に読むページ