[BUG] /api/oauth/usage endpoint returns persistent 429 for Claude Max users (retry-after: 0)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The /api/oauth/usage endpoint returns HTTP 429 (Rate Limited) persistently for Claude Max ($200/month) users, with retry-after: 0. Despite the header suggesting immediate retry is possible, the endpoint continues returning 429 indefinitely (tested over 5+ minutes with various intervals).

This endpoint is used by third-party status line tools (oh-my-claudecode HUD, claude-code-statusline, etc.) to display 5-hour and weekly usage percentages. The persistent 429 makes it impossible to show usage data.

Evidence

$ curl -s -w "\nHTTP: %{http_code}" \
  -H "Authorization: Bearer <valid_token>" \
  -H "anthropic-beta: oauth-2025-04-20" \
  "https://api.anthropic.com/api/oauth/usage"

{"error":{"message":"Rate limited. Please try again later.","type":"rate_limit_error"}}
HTTP: 429

Verbose headers show:

< HTTP/2 429
< retry-after: 0

• OAuth token is valid (4+ hours remaining, verified via Keychain)
• Token has correct scopes (user:inference, user:profile)
• Same token works for normal Claude Code API calls
• Tested with 30s, 60s, 120s intervals — always 429

What Should Happen?

The endpoint should return usage data (5-hour utilization, weekly utilization, reset times) or return a meaningful retry-after value greater than 0.

Relationship to Existing Issues

• #25805 — Reports rate limit errors without distinguishing usage vs throughput limits. This issue is specifically about the /api/oauth/usage metadata endpoint being rate limited, not the inference API.
• #29579 — Reports API errors at 16% usage. Same underlying problem — the usage query endpoint itself is throttled.
• #29604 — Requests exposing rate limit data in statusline JSON stdin. If this were implemented, third-party tools wouldn't need to call /api/oauth/usage at all — solving this issue at the root.

Impact

Third-party status line tools that poll this endpoint (typically every 30-60s) trigger the rate limit quickly, then get stuck in a permanent 429 loop. This affects the entire ecosystem of custom statuslines built around this endpoint.

Proposed Fix

Any of these would help:

1. Increase rate limit for /api/oauth/usage (it's a lightweight metadata query, not inference)
2. Return proper retry-after header (currently returns 0, which is misleading)
3. Include usage data in statusline JSON (#29604) — eliminates the need for separate API calls entirely

Claude Code Version

v2.1.69

Claude Model

Opus 4.6

Is this a regression?

I don't know

Platform

Anthropic API (Claude Max $200/month)

Operating System

macOS (Darwin 25.3.0, Apple Silicon)

Terminal/Shell

zsh