[BUG] /api/oauth/usage endpoint aggressively rate limits, making usage monitoring unusable
Summary
The https://api.anthropic.com/api/oauth/usage endpoint returns rate_limit_error (HTTP 429) so aggressively that it makes it effectively impossible to poll usage data — even at very low intervals.
Steps to reproduce
- Authenticate via OAuth (standard Claude Code credentials in
~/.claude/.credentials.json) - Call
GET https://api.anthropic.com/api/oauth/usagewith a validBearertoken andanthropic-beta: oauth-2025-04-20 - Repeat the call periodically (e.g. every 30–60 seconds)
After a short burst, subsequent calls return:
{"error":{"message":"Rate limited. Please try again later.","type":"rate_limit_error"}}
The rate limiting then persists indefinitely — retrying every 5 minutes (after full exponential backoff) continues to hit 429s for hours on end.
Observed behavior
- Rate limiting kicks in quickly and does not recover
- Retries at 30s → 60s → 120s → 240s → 300s intervals all return 429
- Once stuck at the 300s cap, the endpoint continues returning 429 for the entire session (observed for 30+ minutes continuously)
- There is no
Retry-Afterheader or any indication of when the limit resets
Diagnostic log showing the progression:
[claude-usage] rate limited, backing off 30s
[claude-usage] rate limited, backing off 60s
[claude-usage] rate limited, backing off 120s
[claude-usage] rate limited, backing off 240s
[claude-usage] rate limited, backing off 300s
[claude-usage] rate limited, backing off 300s ← stuck here indefinitely
[claude-usage] rate limited, backing off 300s
[claude-usage] rate limited, backing off 300s
Expected behavior
The usage endpoint should:
- Support reasonable polling intervals (30–60 seconds) without triggering 429s — usage data only changes every few hours at most
- Return a
Retry-Afterheader when rate limiting so clients can back off intelligently - Apply a much higher rate limit ceiling — this is a read-only stats endpoint, not an inference endpoint
Impact
This breaks any tool that displays live Claude usage (quota bars in tmux statuslines, dashboard widgets, IDE plugins, etc.). Claude Code itself exposes usage in its statusline via this endpoint — users building on that same API get frozen/stale data and cannot reliably monitor their quota.
Environment
- Claude Code version: latest
- OS: macOS (Darwin 25.2.0)
- Auth: OAuth via
~/.claude/.credentials.json
Request
Please either raise the rate limit significantly for this endpoint, add a Retry-After header, or document the intended polling interval so client developers can comply.
This issue has 8 comments on GitHub. Read the full discussion on GitHub ↗