[BUG] Misleading "Rate limit reached" error when model is at capacity — caused me to waste resources creating new account

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?

"API Error: Rate limit reached" is shown when Opus is at server capacity, which is the exact same message as when account usage is actually exceeded.

My /status showed 5% session usage and 1% weekly usage. Because the error message gave no indication it was a model-specific issue, I spent hours debugging, and even created a new account — wasting significant time and money.

The fix was simply switching to Sonnet with /model. One clear error message would have saved all of that effort.

Please differentiate error messages:

• Account limit hit → show usage % and reset time
• Model at capacity → suggest switching models with /model

Environment

• Plan: (Pro )
• Claude Code version: 2.1.77 (Claude Code)
• OS: window

What Should Happen?

When Opus is at capacity but account usage is low, the error should say something like "Opus is at capacity, try /model to switch" instead of the generic "Rate limit reached."

Error Messages/Logs

When Opus is under server load, Claude Code shows "API Error: Rate limit reached" — the exact same message as when account usage is actually exceeded.

Steps to Reproduce

1. Run /status → 5% session, 1% weekly
2. Send any message while using Opus
3. Get "API Error: Rate limit reached"
4. Switch to Sonnet via /model → works immediately

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

2.1.77

Claude Code Version

2.1.77

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

PowerShell

Additional Information

Problem

When Opus is under server load, Claude Code shows "API Error: Rate limit reached" — the exact same message as when account usage is actually exceeded.

My /status showed 5% session, 1% weekly usage. The error gave no indication that the issue was model-specific congestion.

What I did because of this misleading error

• Spent hours debugging my account
• Created an entirely new account
• Wasted significant time and money

The fix? Just switching to Sonnet with /model. That's it.

Request

Please show different error messages:

• Account limit: "Rate limit reached. Usage: X%. Resets at Y."
• Model congestion: "Opus is at capacity. Switch to another model with /model."

One clear sentence would have saved me hours of wasted effort.