故障排查
Error reference
Error reference 这一页讲的，就是 Error reference 这件事在 Claude Code 里到底怎么用。
页面信息
这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。
如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。
这一页先讲明白
这页主要讲 Error reference：Look up Claude Code runtime error messages with what each one means and how to fix it.
你可以把它当成"Troubleshooting"这块里专门管这一摊事的说明书。
你可以把"Error reference"理解成 Troubleshooting 这一栏里的一把专门工具。这页不是让你背书，而是教你什么时候该把这把工具拿出来。
原文这页大多会按 Find your error、Automatic retries、Server errors、API Error: 500 Internal server error 这些环节往下讲。
翻成人话，大概就是：API Error: 500 Internal server error
第一，先别一上来全开全配。先按最小一步试通，确认没跑偏，再继续往下加。
第二，命令、配置名、参数名这些硬东西尽量保留原样。人话解释是帮你听懂，不是帮你改关键字。
第三，照着原文这几个环节挨个过：Find your error -> Automatic retries -> Server errors -> API Error: 500 Internal server error。像下地先看水路、再试机器、再正式开干，一步一步最稳。
原页关键片段：API Error: 500 Internal server error
看到这里，别光点头，下面这条命令先跑起来再说。
API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"}} · check status.claude.com原页关键片段：API Error: Repeated 529 Overloaded errors
真到动手的时候了，下面这条直接敲一遍，看它回什么。
API Error: Repeated 529 Overloaded errors · check status.claude.com原页关键片段：Request timed out
最省事的做法，就是把下面这句原样说给 Claude。
Request timed out原页关键片段：Auto mode cannot determine the safety of an action
"Auto mode cannot determine the safety of an action"这一段里最要紧的原始写法在下面，先看它怎么落地。
<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.原页关键片段：You’ve hit your session limit
这一段要真抓重点，通常就抓下面这块原文。
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原页关键片段：Server is temporarily limiting requests
这一段要真抓重点，通常就抓下面这块原文。
API Error: Server is temporarily limiting requests (not your usage limit)原页关键片段：Request rejected (429)
先看下面这块原始片段，等会儿再回头看解释会顺得多。
API Error: Request rejected (429) · this may be a temporary capacity issue原页关键片段：Credit balance is too low
到这里其实就剩一句话，把下面这句发出去就行。
Credit balance is too low原页关键片段：Not logged in
下面这块是这一段最值钱的原文样板，先对着看一眼。
Not logged in · Please run /login原页关键片段：Invalid API key
下面这块是这一段最值钱的原文样板，先对着看一眼。
Invalid API key · Fix external API key原页关键片段：This organization has been disabled
先看下面这块原始片段，等会儿再回头看解释会顺得多。
Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials
API Error: 400 ... This organization has been disabled.原页关键片段：Routines are disabled by your organization’s policy
最省事的做法，就是把下面这句原样说给 Claude。
Routines are disabled by your organization's policy.Documentation Index
这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。
Find your error
这里不是让你背"Find your error"这个词，而是让你看它真干活时怎么使。
Automatic retries
这一块主要是在说"Automatic retries"真到手上该怎么用，哪里最容易踩坑。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Server errors
这一段主要是在把"Server errors"讲实，不是只摆个标题给你看。
API Error: 500 Internal server error
这一块主要是在说"API Error: 500 Internal server error"真到手上该怎么用，哪里最容易踩坑。
API Error: 500 Internal server error
看到这里，别光点头，下面这条命令先跑起来再说。
API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"}} · check status.claude.comAPI Error: Repeated 529 Overloaded errors
这里主要是在交代"API Error: Repeated 529 Overloaded errors"这一块会碰到哪些事。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
API Error: Repeated 529 Overloaded errors
真到动手的时候了，下面这条直接敲一遍，看它回什么。
API Error: Repeated 529 Overloaded errors · check status.claude.comRequest timed out
这段看着像个标题，其实是在说"Request timed out"管到哪儿。
Request timed out
最省事的做法，就是把下面这句原样说给 Claude。
Request timed outAuto mode cannot determine the safety of an action
这一段不只是挂个标题，它是在说明"Auto mode cannot determine the safety of an action"这一块到底负责什么。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Usage limits
看到这里，就把"Usage limits"当成一件真要上手的活来看。
You’ve hit your session limit
这一段主要是在把"You’ve hit your session limit"讲实，不是只摆个标题给你看。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
You’ve hit your session limit
这一段要真抓重点，通常就抓下面这块原文。
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:45pmServer is temporarily limiting requests
这段看着像个标题，其实是在说"Server is temporarily limiting requests"管到哪儿。
Server is temporarily limiting requests
这一段要真抓重点，通常就抓下面这块原文。
API Error: Server is temporarily limiting requests (not your usage limit)Request rejected (429)
看到这里，就把"Request rejected (429)"当成一件真要上手的活来看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Request rejected (429)
先看下面这块原始片段，等会儿再回头看解释会顺得多。
API Error: Request rejected (429) · this may be a temporary capacity issueCredit balance is too low
这一块主要是在说"Credit balance is too low"真到手上该怎么用，哪里最容易踩坑。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Credit balance is too low
到这里其实就剩一句话，把下面这句发出去就行。
Credit balance is too lowAuthentication errors
这一块主要是在说"Authentication errors"真到手上该怎么用，哪里最容易踩坑。
Not logged in
这里不是让你背"Not logged in"这个词，而是让你看它真干活时怎么使。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Not logged in
下面这块是这一段最值钱的原文样板，先对着看一眼。
Not logged in · Please run /loginInvalid API key
这里主要是在交代"Invalid API key"这一块会碰到哪些事。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
This organization has been disabled
看到这里，就把"This organization has been disabled"当成一件真要上手的活来看。
如果你看到环境变量或 settings.json，意思通常都是：这不是会话里临时喊一声就行，而是要把开关真正写进环境或配置。
This organization has been disabled
先看下面这块原始片段，等会儿再回头看解释会顺得多。
Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials
API Error: 400 ... This organization has been disabled.Routines are disabled by your organization’s policy
这一段主要是在把"Routines are disabled by your organization’s policy"讲实，不是只摆个标题给你看。
如果你看到环境变量或 settings.json，意思通常都是：这不是会话里临时喊一声就行，而是要把开关真正写进环境或配置。
Routines are disabled by your organization’s policy
最省事的做法，就是把下面这句原样说给 Claude。
Routines are disabled by your organization's policy.OAuth token revoked or expired
这一段主要是在把"OAuth token revoked or expired"讲实，不是只摆个标题给你看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
OAuth token revoked or expired
这一段要真抓重点，通常就抓下面这块原文。
OAuth token revoked · Please run /login
OAuth token has expired · Please run /login
API Error: 401 ... authentication_errorOAuth scope requirement
这段看着像个标题，其实是在说"OAuth scope requirement"管到哪儿。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Network and connection errors
这里不是让你背"Network and connection errors"这个词，而是让你看它真干活时怎么使。
Unable to connect to API
这一段不只是挂个标题，它是在说明"Unable to connect to API"这一块到底负责什么。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Unable to connect to API
"Unable to connect to API"这一段里最要紧的原始写法在下面，先看它怎么落地。
Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API (ECONNRESET)
Unable to connect to API (ETIMEDOUT)
fetch failed
Request timed out. Check your internet connection and proxy settingsSSL certificate errors
这里不是让你背"SSL certificate errors"这个词，而是让你看它真干活时怎么使。
SSL certificate errors
下面这块是这一段最值钱的原文样板，先对着看一眼。
Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
Unable to connect to API: Self-signed certificate detectedHost not allowed in a cloud session
这里不是让你背"Host not allowed in a cloud session"这个词，而是让你看它真干活时怎么使。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Host not allowed in a cloud session
下面这块是这一段最值钱的原文样板，先对着看一眼。
HTTP 403
x-deny-reason: host_not_allowedRequest errors
这里不是让你背"Request errors"这个词，而是让你看它真干活时怎么使。
Prompt is too long
这段看着像个标题，其实是在说"Prompt is too long"管到哪儿。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Prompt is too long
最省事的做法，就是把下面这句原样说给 Claude。
Prompt is too longError during compaction: Conversation too long
看到这里，就把"Error during compaction: Conversation too long"当成一件真要上手的活来看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Request too large
这里主要是在交代"Request too large"这一块会碰到哪些事。
它强调的是任务切块要刚刚好：太小了不值当分工，太大了又容易一个人闷头干太久，最后返工更重。
Request too large
下面这块是这一段最值钱的原文样板，先对着看一眼。
Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.Image was too large
看到这里，就把"Image was too large"当成一件真要上手的活来看。
Image was too large
先看下面这块原始片段，等会儿再回头看解释会顺得多。
Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed sizePDF errors
别把这段只当成标题看，它其实是在给"PDF errors"划边界。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
PDF errors
先看下面这块原始片段，等会儿再回头看解释会顺得多。
PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.
PDF is password protected. Try removing protection or extracting text first.
The PDF file was not valid. Try converting to a different format first.Extra inputs are not permitted
这里不是让你背"Extra inputs are not permitted"这个词，而是让你看它真干活时怎么使。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Extra inputs are not permitted
下面这块是这一段最值钱的原文样板，先对着看一眼。
API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples
API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header照着做一遍
如果你不想来回翻，就先照这几步顺着做。
每做完一步就看一下结果，再决定要不要继续往下。
第 1 步：API Error: 500 Internal server error
看到这里，别光点头，下面这条命令先跑起来再说。
API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"}} · check status.claude.com第 2 步：API Error: Repeated 529 Overloaded errors
真到动手的时候了，下面这条直接敲一遍，看它回什么。
API Error: Repeated 529 Overloaded errors · check status.claude.com第 3 步：Request timed out
最省事的做法，就是把下面这句原样说给 Claude。
Request timed out第 4 步：Auto mode cannot determine the safety of an action
"Auto mode cannot determine the safety of an action"这一段里最要紧的原始写法在下面，先看它怎么落地。
<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.一眼看懂这一页
先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。
Error reference
|
v
这是 Troubleshooting 里的一摊要紧活
|
v
先弄懂，再下手文末提醒
这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。
人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。