Error Codes 专题¶

重要性：⭐⭐（错误码系统——MCP / 内部 / 业务 / HTTP 各类错误码） 真实位置：src/utils/errors.ts（推测）+ src/services/mcp/auth.ts（-32042 等）角色：定义项目内 / MCP 协议 / API 的错误码关联：topics/mcp-elicitation.md、analysis/error-handling-overview.md

1. 错误码是什么¶

错误码 = 标准化的错误标识 - 数字 / 字符串 - 业务 / 协议 / 内部 - 让上层做 catch / 显示

Claude Code 的错误码来源： - JSON-RPC 错误（MCP） - HTTP 错误（推测） - 内部业务错误 - Claude API 错误（推测）

2. 4 大错误码来源¶

┌────────────────────────────────────┐
│  1. JSON-RPC 标准错误（-32700 ~ -32000）│
│  2. MCP 扩展错误（-32042 elicitation）│
│  3. 业务自定义错误                   │
│  4. Claude API 错误（推测）         │
└────────────────────────────────────┘

4 来源。

3. JSON-RPC 2.0 标准错误¶

错误码	名称	含义
-32700	Parse error	JSON 解析失败
-32600	Invalid Request	请求无效
-32601	Method not found	方法不存在
-32602	Invalid params	参数无效
-32603	Internal error	内部错误
-32099 ~ -32000	Server error	服务器错误（保留）

6 个标准 + 100 个服务器错误。

4. MCP 扩展错误码¶

4.1 -32042 Elicitation¶

// MCP server 工具调用返回 -32042
// 错误中包含 ElicitRequestURLParams

-32042 = server 要求 elicitation。

详见 mcp-elicitation.md。

4.2 其他 MCP 错误（推测）¶

-32001（推测）= 鉴权失败
-32002（推测）= 资源不存在
等等

5-10 个 MCP 错误（推测）。

5. 业务自定义错误类¶

5.1 命名错误类（详细见 error-handling-overview.md）¶

错误类	触发
`McpAuthError`	MCP 鉴权失败
`McpSessionExpiredError`	MCP session 过期
`AuthenticationCancelledError`	用户取消 OAuth
`GcpCredentialsTimeoutError`	GCP 5s 超时
`FileTooLargeError`	文件过大
`MaxFileReadTokenExceededError`	token 超限
`TeleportOperationError`	teleport 失败

7+ 个。

5.2 Telemetry Safe 错误¶

TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
McpToolCallError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS

2 类 类型级安全错误。

6. HTTP 错误码（推测）¶

错误码	含义
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable

7+ 个 HTTP 状态码。

7. 4 类错误处理模式¶

7.1 标准错误 → throw¶

throw new Error('msg')

简单。

7.2 命名错误 → 业务 catch¶

try {
  await mcpOperation()
} catch (e) {
  if (e instanceof McpAuthError) {
    // 处理
  }
}

类型化。

7.3 安全错误 → 上报¶

logError(new McpToolCallError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS(...))

可上报。

7.4 错误码 → 重试¶

// -32042 触发 elicitation
// 401 触发 OAuth refresh
// 429 触发 backoff

自动重试。

8. errorSchema（推测）¶

const ErrorSchema = z.object({
  code: z.string(),
  message: z.string(),
  details: z.record(z.any()).optional(),
})

zod schema —— 错误结构化。

9. 错误码 vs 错误类¶

维度	错误码	错误类
形态	数字 / 字符串	Class
协议	跨语言	TS 专属
序列化	简单	需 JSON.stringify
类型检查	需手动	TS 编译时
catch	switch/if	instanceof

2 套体系 —— 项目用两者。

10. 推测的错误码完整列表¶

码	含义
-32700	JSON parse error
-32600	Invalid Request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32042	MCP Elicitation
-32099	MCP server error (start)
401	HTTP Unauthorized
403	HTTP Forbidden
404	HTTP Not Found
429	HTTP Rate Limit
500	HTTP Server Error
AUTH_FAILED	自定义
BUDGET_EXCEEDED	自定义
SESSION_NOT_FOUND	自定义
PERMISSION_DENIED	自定义
...	...

20+ 个。

11. 错误码 + 重试¶

11.1 401 → OAuth refresh¶

if (error.code === 401) {
  // refresh token
}

自动重试。

11.2 429 → backoff¶

if (error.code === 429) {
  // exponential backoff
}

指数退避。

11.3 -32042 → elicitation¶

if (error.code === -32042) {
  // handleElicitation
}

Elicitation 触发。

11.4 5xx → retry with backoff¶

if (error.code >= 500) {
  // server error, retry
}

5xx 重试。

12. 用户友好的错误信息¶

12.1 错误翻译¶

function enhanceGitPullErrorMessages(result): ... {
  // git fatal: ... → 中文友好
}

错误翻译。

12.2 错误脱敏¶

redactUrlCredentials, redactHeaders

不暴露 密码。

12.3 错误截断¶

const MAX_MCP_DESCRIPTION_LENGTH = 2048

2KB 截断。

13. 错误日志结构¶

logError(error) {
  // 1. error class name
  // 2. error code
  // 3. error message
  // 4. stack trace (dev)
  // 5. context (when, where, who)
  // 6. telemetry
}

6 字段（推测）。

14. 关键设计模式¶

14.1 4 来源错误码¶

JSON-RPC / MCP / 业务 / HTTP。

14.2 命名错误类¶

业务可 catch。

14.3 Telemetry Safe¶

类型级契约。

14.4 错误码 + 重试¶

触发对应动作。

14.5 错误翻译¶

用户友好。

14.6 错误脱敏¶

不暴露密码。

14.7 错误截断¶

2KB 上限。

14.8 错误日志¶

6 字段。

15. 关键洞察¶

15.1 4 来源¶

JSON-RPC / MCP / 业务 / HTTP。

15.2 错误码 + 错误类¶

两套体系。

15.3 7+ 命名错误类¶

业务可 catch。

15.4 Telemetry Safe¶

类型级安全。

15.5 错误码 + 重试¶

触发对应动作。

15.6 错误翻译¶

用户友好。

15.7 错误脱敏¶

不暴露密码。

15.8 错误截断¶

2KB。

15.9 zod schema¶

错误结构化。

15.10 6 字段日志¶

完整上下文。

16. 改进方向¶

16.1 统一错误基类¶

class ClaudeError extends Error { code: ErrorCode }

统一基类。

16.2 错误码国际化¶

// 错误码 → 多语言翻译

i18n 错误。

16.3 错误码 dashboard¶

// 错误码频次统计

监控 dashboard。

16.4 错误恢复策略¶

// 自动恢复 / fallback

恢复策略。

17. 阅读建议¶

看 utils/errors.ts —— 基础错误
看 mcp/auth.ts -32042 —— elicitation
看 services/mcp/auth.ts 错误处理 —— MCP 错误
grep class.*Error 全文 —— 命名错误类
grep BashCode\|error.code 全文 —— 错误码

18. 与其他专题的关系¶

文件	关系
`mcp-elicitation.md`	-32042
`authentication.md`	401 refresh
`cache-strategies.md`	429 backoff
`analysis/error-handling-overview.md`	整体