docs(readme): add Troubleshooting section for upstream API errors#58789
Open
ademczuk wants to merge 1 commit into
Open
docs(readme): add Troubleshooting section for upstream API errors#58789ademczuk wants to merge 1 commit into
ademczuk wants to merge 1 commit into
Conversation
The current README points users at the GitHub issue tracker for any error
they see in the terminal. In practice, a sizable fraction of recent open
issues (40+ from mid-March through mid-April 2026) are reports of upstream
API service errors that the CLI is surfacing verbatim:
API Error: 500 {"type":"error","error":{"type":"api_error","
message":"Internal server error"},"request_id":"req_..."}
Claude may be experiencing issues. Check status.anthropic.com
These are not client bugs - they map to incident windows on
status.claude.com (e.g. "Elevated errors across Claude Models" on Apr 13
and Apr 15) and resolve when the service-side incident does. The
`request_id` is server-side and the trace lives there.
Add a Troubleshooting section between Plugins and Reporting Bugs that
walks a user through:
- Reading the error correctly (api_error 500 is upstream, not client)
- Checking the status page first
- Retrying / switching model
- Searching existing issues before filing
- When it does make sense to escalate, and what to include (request_id)
Same template applies to overloaded_error and rate_limit_error, which I
called out briefly so users hit the right action for each error type
rather than treating every server response as a bug.
Goal is to reduce the duplicate-filing rate on transient incidents
without changing any client behaviour or making promises about the
CLI's internal handling, which I have no visibility into.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
Adds a short
Troubleshooting upstream API errorssection to README.md, placed betweenPluginsandReporting Bugs. The position is intentional: a user who hits an error reads top-down and hits the triage guidance before they get to the "file a GitHub issue" link.The section explains the most common upstream-error pattern users currently see (HTTP 500 +
api_error+ arequest_id), walks through the right diagnostic steps (status page, retry, model swap, search before filing), and notes that the same flow applies tooverloaded_errorandrate_limit_errorso each error type points users at the right action.No behavioural change. README-only. 21 added lines, no removals.
Why
Looking at currently-open issues in this tracker, 40+ are reports of the same upstream 500 surface, filed in clusters that line up with status-page incidents:
The status page shows matching incident windows ("Elevated errors across Claude Models" on Apr 13, model-specific elevated errors on Apr 15, further windows on May 8 / 12 / 13). The duplicates are users seeing the JSON in their terminal, not finding a section in this README explaining what it means, and reasonably concluding it must be a Claude Code bug to report.
A short troubleshooting section in the README is the smallest change that can address that: it teaches readers to recognise the upstream signal, points them at the right surface (status.claude.com), and surfaces the
request_idso escalation has the data the server side needs. It does not promise any change in CLI behaviour, which I have no visibility into from outside.What I considered and didn't do
Verification