【要約】CodexBarWinが「Claude:N/A」に固まる問題を直した話(HTTP 429対応) [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
開発者が作成したWindows用ウィジェットCodexBarWinにおいて、Claude Codeの使用量表示が「Claude:N/A」のまま更新不能になる問題が発生した。開発者は、ツールの信頼性を維持するために、表示が固まる原因の特定と修正を迫られた。
- ・原因はAnthropicの非公式エンドポイントに対する過剰なリクエストによるHTTP 429エラーである。
- ・既存の設計ではエラー理由を区別できず、ユーザーは状況を判別できなかった。
- ・レート制限中もポーリングが継続され、APIへの負荷が続く悪循環に陥っていた。
// Approach
開発者はAPIのレスポンスに基づいた制御ロジックを導入し、通信の最適化とUXの向上を図った。実装にあたっては、
ClaudeUsagePollerクラスを新設し、通信タイミングの一元管理を行った。- ・
Retry-Afterヘッダーを解析し、指定秒数まで再送を自動停止する仕組みを実装した。 - ・通信間隔を最低5分間に制限（クランプ）し、APIへの負荷を抑制した。
- ・取得失敗時も直近の成功値を「stale」として表示し、情報の断絶を防いだ。
- ・429エラー時は「RATE LIMITED」と明示し、原因を可視化した。
- ・
sleep()を使わず「次回通信可能時刻」を管理する非ブロッキングな設計を採用した。
// Result
適切なレート制限制御により、ウィジェットの安定性と情報の継続性が向上した。これにより、API制限下でもツールが「停止」しているのか「制限」されているのかが明確になり、ユーザー体験が劇的に改善された。
- ・56件のユニットテストにより、Retry-Afterのパースやクランプ制御の正確性を検証した。
- ・API制限下でも「RATE LIMITED」表示と直近値の保持により、ユーザーが状況を理解可能になった。
- ・非ブロッキングな設計により、ウィジェット終了時のスレッド競合問題も回避した。
Senior Engineer Insight
> APIのレート制限は、外部サービスを利用する開発において避けて通れない課題だ。本件の優れた点は、単なるリトライではなく「通信間隔のクランプ」と「情報の継続性（stale表示）」を組み合わせ、UXとAPI負荷のバランスを最適化した点にある。特に、
sleep()を使わず「次回通信可能時刻」を管理する設計は、非同期処理やスレッド管理の観点からも極めて実戦的だ。低レイテンシや高い応答性が求められる現場でも、こうした「状態に基づいた制御」は定石として通用する。