Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Error reference

Look up Claude Code runtime error messages with what each one means and how to fix it.

This page lists runtime errors Claude Code displays and how to recover from each one, plus what to check when responses seem off without an error. For installation errors such as command not found or TLS failures during setup, see Troubleshooting.

These errors and recovery commands apply across the CLI, the Desktop app, and Claude Code on the web, since all three wrap the same Claude Code CLI. For surface-specific issues, see the troubleshooting section on that surface's page.

Claude Code calls the Claude API for model responses, so most runtime errors map to an underlying API error code. This page covers what each error means inside Claude Code and how to recover. For the raw HTTP status code definitions, see the Claude Platform error reference.

Find your error

Match the message you see in your terminal to a section below.

Automatic retries

Claude Code retries transient failures before showing you an error. Server errors, overloaded responses, request timeouts, temporary 429 throttles, and dropped connections are all retried up to 10 times with exponential backoff. While retrying, the spinner shows a Retrying in Ns · attempt x/y countdown.

When you see one of the errors on this page, those retries have already been exhausted. You can tune the behavior with two environment variables:

Server errors

These errors come from Anthropic infrastructure rather than your account or request.

API Error: 500 Internal server error

Claude Code shows the raw API response body for any 5xx status. The example below shows a 500 response:

API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"}} · check status.claude.com

This indicates an unexpected failure inside the API. It is not caused by your prompt, settings, or account.

What to do:

• Check status.claude.com for active incidents
• Wait a minute, then send your message again. Your original message is still in the conversation, so for a long prompt you can type try again instead of pasting the whole thing.
• If the error persists with no posted incident, run /feedback so Anthropic can investigate with your request details. See Report an error if /feedback is unavailable on your provider.

API Error: Repeated 529 Overloaded errors

The API is temporarily at capacity across all users. Claude Code has already retried several times before showing this message:

API Error: Repeated 529 Overloaded errors · check status.claude.com

A 529 is not your usage limit and does not count against your quota.

What to do:

• Check status.claude.com for capacity notices
• Try again in a few minutes
• Run /model and switch to a different model to keep working, since capacity is tracked per model. Claude Code prompts you to do this when one model is under particularly high load, for example Opus is experiencing high load, please use /model to switch to Sonnet.

Request timed out

The API did not respond before the connection deadline.

Request timed out

This can happen during periods of high load or when a very large response is being generated. The default request timeout is 10 minutes.

What to do:

• Retry the request
• For long-running tasks, break the work into smaller prompts
• If a slow network or proxy is the cause, raise API_TIMEOUT_MS as described in Automatic retries
• If timeouts are frequent and your network is otherwise healthy, see Network and connection errors below

Auto mode cannot determine the safety of an action

The model that auto mode uses to classify actions is overloaded, so auto mode blocked the action instead of approving it unchecked.

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

Reads, searches, and edits inside your working directory skip the classifier, so they keep working during the outage.

What to do:

• Retry after a few seconds; Claude sees the same message and usually retries on its own
• If retries keep failing, continue with read-only tasks and come back to the blocked action later
• This is transient and unrelated to auto mode eligibility; you do not need to change settings

Usage limits

These errors mean a quota tied to your account or plan has been reached. They are distinct from server errors, which affect everyone.

You've hit your session limit

Subscription plans include a rolling usage allowance. When it runs out you see one of these messages:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

Claude Code blocks further requests until the reset time shown in the message.

What to do:

• Wait for the reset time shown in the error
• Run /usage to see your plan limits and when they reset
• Run /extra-usage to buy additional usage on Pro and Max, or to request it from your admin on Team and Enterprise. See Extra usage for paid plans for how this is billed.
• To upgrade your plan for higher base limits, see claude.com/pricing

To watch your remaining allowance before you hit the limit, add the rate_limits fields to a custom status line, or in the Desktop app click the usage ring next to the model picker.

Server is temporarily limiting requests

The API applied a short-lived throttle that is unrelated to your plan quota.

API Error: Server is temporarily limiting requests (not your usage limit)

This is retried automatically before being shown.

What to do:

• Wait briefly and try again
• Check status.claude.com if it persists

Request rejected (429)

You have hit the rate limit configured for your API key, Amazon Bedrock project, or Google Vertex AI project.

API Error: Request rejected (429) · this may be a temporary capacity issue

What to do:

• Run /status and confirm the active credential is the one you expect. A stray ANTHROPIC_API_KEY in your environment can route requests through a low-tier key instead of your subscription.
• Check your provider console for the active limits and request a higher tier if needed
• For Anthropic API keys, see the rate limits reference for how tiers work and how to set per-workspace caps
• Reduce concurrency: lower CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, avoid running many parallel subagents, or switch to a smaller model with /model for high-volume scripted runs

Credit balance is too low

Your Console organization has run out of prepaid credits.

Credit balance is too low

What to do:

• Add credits at platform.claude.com/settings/billing, and consider enabling auto-reload there so the balance refills before it hits zero
• Switch to subscription authentication with /login if you have a Pro, Max, Te