Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Troubleshooting docs omit server-error guidance and usage-vs-rate-limit distinction [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#48089•Fetched 2026-04-15 06:33:32
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3

Error Message

Runtime API error troubleshooting for subscription usage limits, server-side rate limits, and 5xx/529 service errors The troubleshooting page currently lists installation and auth failures, but no runtime service-error section:

| OAuth error or 403 Forbidden | Fix authentication | 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 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. Add a short runtime error subsection to troubleshooting covering three distinct cases:

  1. 5xx/529 service error | https://code.claude.com/docs/en/troubleshooting | Primary location for explaining runtime API error categories and recovery steps |

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

RAW_BUFFERClick to expand / collapse

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 |

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:

PageContext
https://code.claude.com/docs/en/troubleshootingPrimary 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-codeVS 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

extent analysis

TL;DR

Add a runtime error subsection to the troubleshooting page to distinguish between plan usage limits, server-side rate limits, and 5xx/529 service errors.

Guidance

  • Update the troubleshooting page at https://code.claude.com/docs/en/troubleshooting to include a new subsection covering the three distinct error cases: plan or subscription usage limit reached, server-side rate limit, and 5xx/529 service error.
  • Add a brief note to the /usage command description in the commands page and VS Code command-menu docs to clarify that /usage shows subscription/plan usage information, not general server health.
  • Ensure the new subsection explains the differences between plan usage limits and server-side rate limits, and provides a recovery path for 5xx/529 service-side failures by linking to https://status.claude.com.
  • Review the changelog entry for v2.1.108 to ensure the documentation accurately reflects the improved error messages and user-facing changes.

Example

A possible addition to the troubleshooting page could be:

### Runtime API Errors
#### 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

#### 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

#### 5xx/529 Service Error
* Explain that this indicates a Claude-side outage or degradation
* Link users to `https://status.claude.com`

Notes

The suggested improvement should be applied to the three affected pages: troubleshooting, commands, and VS Code documentation. The exact wording and formatting may vary depending on the existing documentation style and tone.

Recommendation

Apply the suggested workaround by adding the runtime error subsection to the troubleshooting page and updating the /usage command descriptions. This will provide users with clear guidance on distinguishing between plan usage limits, server-side rate limits, and 5xx/529 service errors, and improve their overall experience with the feature.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#model download#runtime error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING