Error UX: throttle 'not your usage limit' vs opaque 'invalid_request' indistinguishable on Max plan

Summary

Two related error-UX problems make it hard to tell a transient server throttle apart from a real quota/bug on a Max plan, during heavy/automated Claude Code sessions (Workflow tool + many subagents, long-running /goal automation).

1. Server is temporarily limiting requests (not your usage limit) · Rate limited

• Occurs mid-session during bursty activity (multi-agent Workflow, rapid tool calls).
• The message explicitly says it is not the usage limit, yet gives no actionable guidance (no retry-after, no indication of the per-account request-rate/burst ceiling).
• On a paid Max subscription this reads as "I'm paying the top tier and still getting throttled with no explanation."

Request: clearly distinguish request-rate/burst throttling from usage quota in the message, and include retry guidance (e.g. retry-after seconds). Document the burst limits that apply to automated/multi-agent sessions.

2. Opaque API Error: invalid_request

• Recurs with no detail, specifically on prompts in security / reverse-engineering topics.
• Strongly looks like a model refusal (stop_reason: "refusal") being surfaced to the CLI as a generic invalid_request, instead of an explicit refusal reason.

Request: surface the actual stop_reason (e.g. refusal) so users can tell a refusal apart from a malformed-request bug or a transient API error.

Impact

When a long automated session hits either of these, the four cases — transient throttle, quota exhaustion, model refusal, real bug — are indistinguishable from the error text, which wastes significant debugging time and erodes trust in the paid tier.

Environment

• Claude Code CLI (latest), Opus 4.x, macOS.
• Max plan.
• Triggered during a Workflow-tool / multi-subagent run and a long-running self-paced automation.

Asks (summary)

1. Differentiate throttle vs quota in the rate-limit message + add retry guidance.
2. Surface stop_reason: refusal explicitly instead of invalid_request.