What you will be able to do
- Use the error reference to sort a Claude Code message into the right failure category
- Tell which failures Claude Code retries automatically and which ones need you to act
- Recover a session after a refusal or a safeguard flag, and report memory problems safely
- Use the session event stream and threads to find which agent in a multiagent session is stuck
1.Sort the message into a category before you act
Claude Code's error reference starts with a lookup table. You find the exact message text, and the table tells you which section explains it. The category matters because each one points to a different owner and a different fix. Server errors are on the API side. Usage limits are about plan or spend. Authentication errors need a fresh login or credentials. Network errors usually involve a proxy or TLS. Request errors come from the content of the conversation itself.
| Message | Section |
|---|---|
| API Error: Repeated 529 Overloaded errors | Server errors |
| Credit balance is too low | Usage limits |
| OAuth token refresh failed — run /login to re-authenticate | Authentication |
| SSL certificate verification failed | Network |
| Prompt is too long / Input is too long for requested model | Request errors |
| MCP server "<name>" requires re-authorization (token expired) | Authentication |
Problems that happen during installation or update have their own fixes. For example, exit code 137 during install usually means the system ran out of memory. For any install issue, the docs say to "Run claude doctor from your shell for installation diagnostics".
Checkpoint 1 of 5· Check yourself
A developer sees "Credit balance is too low". Which section of the error reference covers it?
A low credit balance is a usage-limit condition. It isn't an outage or a credential problem, so retrying or logging in again won't fix it.
“Credit balance is too low | Usage limits”Source: code.claude.com
Sources1
2.What Claude Code retries for you, and what it won't
Claude Code retries many transient failures with backoff, so a message you see while a retry is in progress is not always the final result. Retried failures include "Server errors, overloaded responses, and request timeouts that arrive before any of Claude’s response has streamed", and also temporary 429 throttles.
Dropped connections and stalled responses have their own rules. If a connection drops before Claude has finished any part of its response, the request is sent again. A stalled stream is a different case: Claude Code "aborts the stalled connection and re-issues the request at most once, outside the 10-attempt budget above." If the second attempt also stalls after thinking, the turn ends with a specific message: The response stalled before a response was produced.
A context-limit rejection is handled differently. Sending the same request again would fail the same way, so Claude Code retries with a smaller max_tokens. If no smaller value fits, it stops retrying and compacts the conversation instead. Look up the final message in the error reference. Messages shown while retries are still running are not the final result.
Checkpoint 2 of 5· Check yourself
A request is rejected because input plus max_tokens exceeds the context limit. What does Claude Code do?
Sending an unchanged request again would fail the same way. Claude Code reduces max_tokens first and compacts the conversation when no smaller value can fit.
“Re-sending it unchanged would fail the same way, so Claude Code retries with a reduced max_tokens”Source: code.claude.com
Checkpoint 3 of 5· Exam question
An admin sets model: claude-opus-4-8 in the project's .claude/settings.json so the whole team defaults to Opus. One engineer's sessions keep starting on Sonnet instead, and /status confirms project settings are being read. What is the most likely explanation?
Correct answer: A — The engineer has the same model key set in .claude/settings.local.json, which overrides the project-level settings.json.
- A. Correct. Among local, project, and user scopes, the closer scope (local) overrides the broader one (project). A model key duplicated in settings.local.json would take precedence over the project's settings.json even though /status confirms project settings loaded.
- B. Incorrect. The absence of an environment variable does not prevent Claude Code from reading a project-level setting; settings.json values apply without requiring a matching environment variable.
- C. Incorrect. There is no documented behavior where an older version silently ignores the model key; a stale or invalid model reference produces an explicit error rather than silent fallback to a different model.
- D. Incorrect. There is no time-based restriction limiting settings.json defaults to projects created after the setting was added; settings apply to the project directory regardless of when the file was written.
Sources1
3.Recovering a session: refusals, context pressure and memory
Some failures come from the conversation itself, so retrying won't help. You have to change the conversation. After a refusal or a safeguard flag, "Press Esc twice or run /rewind to step back to a checkpoint before the turn that triggered the refusal", then take a different approach. If you can't tell which turn caused it, run /clear. "Your previous conversation is preserved on disk and remains available in /resume." Headless runs work differently: "In non-interactive mode (-p), where rewind is unavailable, retry with a rephrased prompt in a new session without --continue." Policy checks vary by model, so switching models with --model may also help.
You also handle slow or memory-heavy sessions by changing the context. Run /compact with a focus that drops large output. "Move the large-file work to a subagent so it runs in a separate context window", or run /clear. If memory stays high, you have two options. You can investigate it yourself: "if the summary says most memory is JS heap, open the .heapsnapshot file in Chrome DevTools". Or you can open a GitHub issue and attach only the -diagnostics.json file. It "carries the statistics behind the printed summary and no conversation content or credentials", so it's the file that is safe to share.
Checkpoint 4 of 5· Check yourself
A CI job running claude -p hits a refusal. What recovery do the docs recommend?
Rewind isn't available in non-interactive mode. Continuing would carry the refused content forward, so start a fresh session with a rephrased prompt.
“In non-interactive mode (-p), where rewind is unavailable, retry with a rephrased prompt in a new session without --continue.”Source: code.claude.com
4.Finding the stuck agent in a multiagent session
When a Managed Agents session with several agents misbehaves in production, the first question is which agent is responsible. The session-level event stream at /v1/sessions/{session_id}/events/stream acts as the primary thread, "containing a condensed view of all activity across all threads". It doesn't include everything subagents do. You only "see the start and end of their work, and blocking events such as tool permission requests". If a subagent is waiting on a permission, the event stream shows it.
For anything more detailed, "Session threads are where you drill into a specific agent's activity." Listing the threads shows the status of each agent:
for thread in client.beta.sessions.threads.list(session.id):
print(f"[{thread.agent.name}] {thread.status}")The list includes the primary thread, and parent_thread_id is null for that thread. Read the session status carefully, because it is an aggregate. If any one thread is still running, the whole session shows as running. A session that looks hung may therefore be waiting on a single subagent, and the per-thread list shows you which one. Budgets can also pause work. A session budget is one cap shared by all threads, and "As the cap is reached, threads pause independently". Message events are named from the point of view of the stream they appear on. For example, agent.thread_message_received means this thread received a message from another thread.
Checkpoint 5 of 5· Check yourself
A session has been showing running for an hour, and the coordinator looks finished. What explains this, and where should you look next?
Session status combines the status of all threads, so one running subagent keeps the whole session running. Listing the threads shows which one it is.
“if at least one thread is running, then the overall session status is running as well”Source: platform.claude.com
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Every 429 is a temporary throttle that Claude Code will retry until it succeeds.Why is that wrong?
Claude Code doesn't retry a gateway's spend-limit 429 because it isn't a throttle. Treat it as a usage-limit problem.
Covered in What Claude Code retries for you, and what it won't
2.The session-level event stream contains every subagent's full activity, so it's all you need to debug a subagent.Why is that wrong?
The session event stream is a condensed view. You have to open the agent's thread to see what it did in detail.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/errorsOfficial docs
“Run claude doctor from your shell for installation diagnostics”
↩︎ Sort the message into a category before you act“Claude Code aborts the stalled connection and re-issues the request at most once, outside the 10-attempt budget above.”
↩︎ What Claude Code retries for you, and what it won't“Server errors, overloaded responses, and request timeouts that arrive before any of Claude’s response has streamed.”
↩︎ What Claude Code retries for you, and what it won't“Press Esc twice or run /rewind to step back to a checkpoint before the turn that triggered the refusal”
↩︎ Recovering a session: refusals, context pressure and memory“Temporary 429 throttles, but not a gateway’s spend-limit 429, which isn’t a throttle”
↩︎ Exam trap 1“Credit balance is too low | Usage limits”
↩︎ Checkpoint“Temporary 429 throttles, but not a gateway’s spend-limit 429, which isn’t a throttle”
↩︎ Prediction“Re-sending it unchanged would fail the same way, so Claude Code retries with a reduced max_tokens”
↩︎ Checkpoint“In non-interactive mode (-p), where rewind is unavailable, retry with a rephrased prompt in a new session without --continue.”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/troubleshootingOfficial docs
“attach only the -diagnostics.json file, which carries the statistics behind the printed summary and no conversation content or credentials”
↩︎ Recovering a session: refusals, context pressure and memory“Move the large-file work to a subagent so it runs in a separate context window”
↩︎ Recovering a session: refusals, context pressure and memory - 3.
“containing a condensed view of all activity across all threads”
↩︎ Finding the stuck agent in a multiagent session“if at least one thread is running, then the overall session status is running as well”
↩︎ Finding the stuck agent in a multiagent session“Session threads are where you drill into a specific agent's activity.”
↩︎ Exam trap 2