[DOCS] Troubleshooting docs omit server-error guidance and usage-vs-rate-limit distinction

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/troubleshooting

Section/Topic

Runtime API error troubleshooting for subscription usage limits, server-side rate limits, and 5xx/529 service errors

Current Documentation

The troubleshooting page currently lists installation and auth failures, but no runtime service-error section:

| OAuth error or 403 Forbidden | [Fix authentication](#authentication-issues) |

The command reference currently describes /usage only at a high level:

| /usage | Show plan usage limits and rate limit status |

The VS Code docs also frame /usage as plan usage UI:

* Command menu: click / or type / to open the command menu. Options include attaching files, switching models, toggling extended thinking, viewing plan usage (/usage), and starting a Remote Control session (/remote-control).

I could not find any code.claude.com page that explains:

• how server-side rate-limit errors differ from plan/subscription usage limits
• that 5xx/529 errors should send users to https://status.claude.com

What's Wrong or Missing?

Changelog v2.1.108 says:

Improved error messages: server rate limits are now distinguished from plan usage limits; 5xx/529 errors show a link to status.claude.com; unknown slash commands suggest the closest match

The docs do not currently explain the first two user-facing parts of that change.

A. No documented distinction between plan usage limits and server-side rate limits

Current docs mention plan usage, subscription usage limits, and generic rate limit status, but they do not tell users that a transient server-side rate-limit error is a different condition from exhausting their own plan usage.

B. No documented recovery path for 5xx/529 service-side failures

The troubleshooting docs do not currently tell users that 5xx/529 errors indicate a Claude-side service problem and that they should check status.claude.com before treating the problem as a local configuration or account issue.

Without this guidance, users can misread a temporary service incident as a billing/quota problem or waste time debugging their local setup.

Suggested Improvement

Add a short runtime error subsection to troubleshooting covering three distinct cases:

1. Plan or subscription usage limit reached

• explain that /usage shows the user's plan usage state
• point to claude.ai/settings/usage or relevant plan/billing guidance

1. Server-side rate limit

• explain that this is temporary service throttling and is not the same as the user's plan usage being exhausted
• recommend retrying after the reset/backoff interval shown by Claude Code

1. 5xx/529 service error

• explain that this indicates a Claude-side outage or degradation
• link users to https://status.claude.com

Also add a brief note anywhere /usage is introduced (commands and VS Code command-menu docs) clarifying that /usage shows subscription/plan usage information, not general server health.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/troubleshooting | Primary location for explaining runtime API error categories and recovery steps |
| https://code.claude.com/docs/en/commands | /usage currently says only “Show plan usage limits and rate limit status” |
| https://code.claude.com/docs/en/vs-code | VS Code command menu describes /usage as viewing plan usage |

Total scope: 3 pages affected

Source: Changelog v2.1.108

Exact changelog entry:

Improved error messages: server rate limits are now distinguished from plan usage limits; 5xx/529 errors show a link to status.claude.com; unknown slash commands suggest the closest match