[BUG] HTTP 400 'prompt is too long' is misreported to the user as 'usage limit reached'

Preflight Checklist

• [x] I have searched existing issues. The closest, #47113, reports the same underlying symptom but is framed as a rate-limit bug — that misframing is exactly what this report is about. The bug itself does not have a clean issue.
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code

What's Wrong?

When the API returns HTTP 400 invalid_request_error with prompt is too long: <N> tokens > 200000 maximum, Claude Code displays a generic "usage limit reached" / rate-limit-style message to the user.

This is wrong in three ways:

1. The user has not hit any usage limit. They have exceeded the per-request context window. Two different problems with two different fixes.
2. The recommended response to "usage limit" is "wait or upgrade." Neither helps. The actual fix is /compact, /clear, or starting a fresh session window.
3. The error is sticky. Once the session is past 200k tokens, every subsequent message also exceeds the limit, so the user sees the same "usage limit" message repeatedly and concludes their plan is broken. Many users end up logging out and back in, which appears to "fix" it because logout discards the session.

I hit this 10+ times in the past 12 hours on a heavy session that involves skills loading SKILL.md files into context. Every time, the CLI told me I was rate-limited when the underlying cause was HTTP 400 prompt-too-long.

#47113 is the same bug from a different reporter. Its title says "rate limit error at 72% token usage" but its body shows the actual error is prompt is too long: 209375 tokens > 200000 maximum. The misframing is strong enough that even reporters call this a rate-limit bug.

What Should Happen?

When the API returns 400 invalid_request_error with prompt is too long, the CLI should show a distinct message such as:

Context window full. This session has exceeded the 200k token limit. Try: - /compact to summarize prior turns - /clear to start fresh in this directory - Start a new session window This is not a usage-limit issue. Your plan is fine.

Rate-limit / usage-limit copy should be reserved for HTTP 429 responses.

Error Messages/Logs

Underlying API error (present in logs, not in the user-facing message):

Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 209375 tokens > 200000 maximum"},"request_id":"req_..."}

User-visible CLI message: a "usage limit reached" / rate-limit string that suggests waiting or upgrading.

Steps to Reproduce

1. Start a session and load enough context to approach 200k tokens. Easiest path: a long working session that invokes several skills (each loading its SKILL.md into context), reads multiple large files, and runs subagent reports.
2. At roughly 190-200k tokens, run any skill that loads more content into context (in my case /push).
3. The next API call returns HTTP 400 invalid_request_error with prompt is too long.
4. Claude Code displays a "usage limit reached" / rate-limit error to the user.
5. User logs out / logs back in believing their plan is rate-limited. This "works" only because logout discards the session.

Suggested Fix

One branch in the error handler. Distinguish:

• HTTP 400 + error.type === 'invalid_request_error' + message starts with prompt is too long → "Context window full" copy with /compact / /clear / new-session guidance.
• HTTP 429 + rate-limit error types → existing usage-limit copy.

Claude Model

Opus (configured for 1M context — separate question whether the 1M flag is being respected when skills load SKILL.md files into context, or whether requests are silently capped at 200k for skill invocations).

Is this a regression?

I don't know

Claude Code Version

Latest as of 2026-05-08 (Claude desktop app on macOS, current production build)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other (Claude desktop app)

Additional Information

Why this is high impact:

• Skills are a primary Claude Code feature. Every skill invocation loads its SKILL.md into context. Heavy-context sessions hit this constantly.
• The misframing trains users to mistrust their plan rather than manage their session.
• The fix is a one-branch change in the error handler. The 400 vs 429 distinction is already in the API response.

Why this is misreporting and not a real rate-limit:

• Logout / login resolves it instantly. A real rate limit would not reset on logout.
• /compact resolves it instantly when the user thinks to try it.
• API logs show 400 invalid_request_error, not 429.