Specific API error silently replaced by generic UI message, hiding actionable remediation

What's wrong

When a session's context crosses the 200K standard limit into 1M territory, the Anthropic API returns a specific, actionable error:

API Error: Usage credits required for 1M context · turn on usage credits at 
claude.ai/settings/usage, or use --model to switch to standard context

Claude Code discards this and surfaces two generic messages instead:

• "Server is temporarily limiting requests — too many requests right now, try again in a moment"
• "Usage limit reached" (red banner)

Both are wrong. This is not a rate limit. It is not a usage quota exhaustion. It is a feature-tier gate. The user is told to wait, when the actual fixes are enabling usage credits or running /compact (though /compact is itself blocked in this state — see #64911). The original error with its remediation steps is present in the raw JSONL transcript but completely invisible in the UI.

How I know the API returned the specific error

The raw session JSONL contains the verbatim API response. The UI message bears no resemblance to it. The discarded error even contains the exact fix (turn on usage credits at claude.ai/settings/usage, or use --model to switch to standard context).

Why this is hard to discover

The only way to observe the discrepancy is to read the raw JSONL. From the UI alone there is no way to distinguish this failure from genuine rate limiting or quota exhaustion. It will therefore always be filed as a symptom and never as the root cause.

What should happen

The specific API error and its remediation steps should be surfaced in the UI, not replaced by a generic fallback. At minimum: if the error body contains actionable text, display it rather than a generic substitute.

Related — why this is not a duplicate

• #62052 ("Misleading 'Usage limit reached' when selecting Sonnet — actually a 1M context tier gate"): In that report, the real API error was surfaced — it appears verbatim in the reporter's error log. Their complaint is that the headline contradicts the detail. Our bug is the opposite: the real API error is never shown at all; only the wrong generic messages appear.
• #61529 ("Contradictory rate-limit messages shown together"): That report describes two contradictory messages both visible on screen simultaneously. Our bug is one wrong message appearing instead of the correct one — the real error is invisible.
• #63929, #64438, #64852, #64327, #64088, #63173, #63703, #63014, #53915 ("Server is temporarily limiting requests" cluster): Those are reports of genuine server-side throughput rate limits. Our case is a feature-tier gate (1M context credits) being misclassified and displayed as a rate limit — different cause, different fix.
• #25805 ("Rate limit errors don't distinguish usage vs throughput limits"): An enhancement request for general error categorization. Our issue is a specific instance where a known, actionable error with an explicit fix is silently replaced by an incorrect generic message.

Environment

• Platform: macOS
• Version: v2.1.158
• Model: claude-sonnet-4-6