[Bug] Rate limit blocking ignores anthropic-ratelimit-unified-representative-claim header

[mgajda]

Bug Description
[BUG] Rate limit triggered despite API reporting 98% quota available (ignores representative-claim)

---

What's Wrong?

Claude Code displays "Usage limit reached" and blocks further requests even though:

1. The API explicitly returns anthropic-ratelimit-unified-status: allowed
2. The representative rate limit window (5-hour) shows 98% quota remaining
3. The /usage command confirms 96% session quota is still available

The client appears to incorrectly use the 7-day utilization metric (73.7% used) instead of respecting the anthropic-ratelimit-unified-representative-claim: five_hour header field.

---

What Should Happen?

Claude Code should:

1. Read the anthropic-ratelimit-unified-representative-claim header to determine which time window is authoritative
2. Use the corresponding utilization metric for that window
3. Only block requests when anthropic-ratelimit-unified-status returns "rate_limited" or the representative window shows 100% utilization
4. Allow requests to proceed when status is "allowed"

---

Steps to Reproduce

1. Use Claude Code normally until 7-day utilization reaches ~70-80%
2. Ensure 5-hour utilization remains low (~1-2%)
3. Continue making requests
4. Observe "Usage limit reached" error despite available quota

Reproduction in this session:

• Session ID: aac5dce7-1d5f-453d-956e-c5219e828796
• Log file: ~/.claude/debug/aac5dce7-1d5f-453d-956e-c5219e828796.txt
• Request IDs: req_011CVeoHF4hrg6oVjdfvoYiv, req_011CVeoHrVRV2d6Ahd9hxbS1

---

Error Messages/Logs

UI displayed:
Usage limit reached ∙ resets 8pm
Opening your options…

API response headers (request: req_011CVeoHrVRV2d6Ahd9hxbS1):
{
"anthropic-ratelimit-unified-status": "allowed",
"anthropic-ratelimit-unified-5h-status": "allowed",
"anthropic-ratelimit-unified-5h-reset": "1764554400",
"anthropic-ratelimit-unified-5h-utilization": "0.018416969696969696",
"anthropic-ratelimit-unified-7d-status": "allowed",
"anthropic-ratelimit-unified-7d-reset": "1764615600",
"anthropic-ratelimit-unified-7d-utilization": "0.7370692663445869",
"anthropic-ratelimit-unified-representative-claim": "five_hour",
"anthropic-ratelimit-unified-fallback-percentage": "0.2",
"anthropic-ratelimit-unified-reset": "1764554400",
"anthropic-ratelimit-unified-overage-disabled-reason": "org_level_disabled"
}

Key metrics from headers:

• Overall status: allowed ✅
• Representative claim: five_hour → This should be used
• 5-hour utilization: 0.018416 = 1.8% used = 98.2% available ✅
• 7-day utilization: 0.7370 = 73.7% used = 26.3% available

/usage command output at time of error:
Current session
████████████████████████████████████████████████ 96% left
Resets 2:59am (Europe/Warsaw)

Current week (all models)
█████████████ 26% left
Resets 7:59pm (Europe/Warsaw)

---

Root Cause Analysis

The client appears to have logic similar to:
// ❌ INCORRECT (current behavior?)
if (headers['anthropic-ratelimit-unified-7d-utilization'] > 0.7) {
showRateLimitError();
}

// ✅ CORRECT (expected behavior)
const representativeClaim = headers['anthropic-ratelimit-unified-representative-claim'];
const utilizationKey = anthropic-ratelimit-unified-${representativeClaim}-utilization;
const status = headers['anthropic-ratelimit-unified-status'];

if (status === 'rate_limited' || headers[utilizationKey] >= 1.0) {
showRateLimitError();
}

---

Impact

Severity: CRITICAL

• Users with low short-term usage but high 7-day cumulative usage are incorrectly blocked
• The 5-hour window is specifically designed to allow bursts even if weekly quota is depleted
• This defeats the purpose of the unified rate limit system's representative claim mechanism
• Users see "96% left" but cannot use the tool

---

Additional Information

Timeline: 2025-11-30 21:39:43 GMT

Debug log excerpt:
[log_a1a1e6, request-id: "req_011CVeoHrVRV2d6Ahd9hxbS1"]
post https://api.anthropic.com/v1/messages?beta=true
succeeded with status 200 in 1976ms

[log_a1a1e6] response start {
url: "https://api.anthropic.com/v1/messages?beta=true",
status: 200,
headers: { ... (full headers above) ... }
}

Observed pattern:

• This occurs consistently when 7-day utilization exceeds ~70%
• Persists even though representative claim (5-hour) has 98%+ available
• Forces users to wait until 7-day reset instead of 5-hour reset

---

Metadata

Claude Code Version: 2.0.55 (latest)

Platform: Anthropic API

Operating System: Linux (6.17.0-7-generic)

Terminal/Shell: Gnome Terminal

Environment Info

• Platform: linux
• Terminal: gnome-terminal
• Version: 2.0.50
• Feedback ID: 0ef92236-d8ae-43d0-8f0d-76d11f76c37c
• Is this a regression? Unknown - may have existed since unified rate limits were introduced
• Model: Haiku (claude-haiku-4-5-20251001)

[github-actions]

Found 3 possible duplicate issues:

1. [Bug] Anthropic API Error: Usage limit reached despite /usage showing available quota #12698
2. Anthropic API Rate Limit Error Incorrectly Blocking Usage #9313
3. [Bug] Anthropic API Error: Rate Limit Exceeded Despite Sub-50% Usage #12542

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #12698.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.