Reference: Error Classes¶

目的：速查 所有命名错误类 关联：topics/error-codes.md、analysis/error-handling-overview.md

1. 总览¶

维度	数字
业务错误类	7+
Telemetry Safe 错误	2
标准 Error	无数

3 维度。

2. 7+ 业务错误类¶

2.1 `McpAuthError` (export)¶

// services/mcp/auth.ts
export class McpAuthError extends Error { ... }

触发：MCP 鉴权失败

catch 方式：

try { ... }
catch (e) {
  if (e instanceof McpAuthError) {
    // 触发 OAuth 重新认证
  }
}

2.2 `McpSessionExpiredError` (不 export)¶

// services/mcp/auth.ts
class McpSessionExpiredError extends Error { ... }

触发：MCP session 过期

catch 方式：用 isMcpSessionExpiredError() 函数。

2.3 `AuthenticationCancelledError` (export)¶

// services/mcp/auth.ts
export class AuthenticationCancelledError extends Error { ... }

触发：用户取消 OAuth

2.4 `GcpCredentialsTimeoutError`¶

// utils/auth.ts (推测)
class GcpCredentialsTimeoutError extends Error {}

触发：GCP 5s 超时

2.5 `FileTooLargeError`¶

// utils/readFileInRange.ts
class FileTooLargeError extends Error {}

触发：文件过大

2.6 `MaxFileReadTokenExceededError`¶

// tools/FileReadTool/FileReadTool.ts
class MaxFileReadTokenExceededError extends Error {}

触发：token 超限

2.7 `TeleportOperationError`¶

// utils/teleport.ts
class TeleportOperationError extends Error {
  formattedMessage: string
}

触发：teleport 失败

3. 2 类 Telemetry Safe 错误¶

3.1 `TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS`¶

// 类型契约
class TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS 
  extends Error { ... }

约束：错误信息可安全上报。

3.2 `McpToolCallError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS`¶

// services/mcp/client.ts
export class McpToolCallError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS 
  extends TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS { ... }

用途：MCP 工具调用失败。

4. 错误类判别函数¶

4.1 `isMcpSessionExpiredError`¶

export function isMcpSessionExpiredError(error: Error): boolean {
  return error instanceof McpSessionExpiredError || 
         error.message.includes('session expired')
}

判别。

5. 5 类错误处理模式¶

5.1 `try/catch` + log¶

try {
  await operation()
} catch (e) {
  logError(e)
  return null
}

最常见。

5.2 `try/catch` + rethrow¶

try {
  await operation()
} catch (e) {
  logError(e)
  throw new McpAuthError('Re-auth required')
}

包装。

5.3 `try/catch` + fallback¶

try {
  return await fastOperation()
} catch (e) {
  return await slowFallback()
}

降级。

5.4 `maybe()` helper¶

async function maybe<A>(label: string, f: () => Promise<A[]>): Promise<A[]> {
  try {
    return await f()
  } catch (e) {
    logError(e)
    return []
  }
}

附件系统用。

5.5 type catch¶

try {
  await operation()
} catch (e) {
  if (e instanceof McpAuthError) {
    // ...
  } else if (e instanceof FileTooLargeError) {
    // ...
  } else {
    throw e
  }
}

类型化。

6. 5 种错误抛出场景¶

6.1 API 错¶

throw new Error('API call failed: ' + response.status)

API。

6.2 验证错¶

const result = schema.safeParse(input)
if (!result.success) {
  throw new Error(`Invalid input: ${result.error.message}`)
}

validate。

6.3 资源错¶

throw new FileTooLargeError(`File ${path} exceeds 10MB`)

resource。

6.4 权限错¶

throw new Error('Permission denied: ' + tool)

permission。

6.5 超时错¶

throw new GcpCredentialsTimeoutError('GCP credentials check timed out')

timeout。

7. 6 个标准错误码（JSON-RPC）¶

码	名称	用途
-32700	Parse error	JSON 解析失败
-32600	Invalid Request	请求无效
-32601	Method not found	方法不存在
-32602	Invalid params	参数无效
-32603	Internal error	内部错误
-32042	Elicitation	MCP elicitation

6 个。

8. 5 个 HTTP 错误码（推测）¶

码	含义
401	Unauthorized（OAuth refresh）
403	Forbidden
404	Not Found
429	Too Many Requests（backoff）
500+	Server Error（retry）

5 个。

9. 错误处理"成熟度"评分¶

模式	评分	备注
命名错误类	⭐⭐⭐⭐	7+ 类
安全错误类	⭐⭐⭐⭐⭐	命名约定强制
重试机制	⭐⭐⭐⭐	401 refresh, git retry
优雅降级	⭐⭐⭐⭐⭐	5+ 模式
错误脱敏	⭐⭐⭐⭐	URL / header
错误翻译	⭐⭐⭐⭐	git / oauth
AbortController	⭐⭐⭐⭐⭐	5+ timeout
信号处理	⭐⭐⭐	SIGINT + exit

总体 ⭐⭐⭐⭐ — 商业级。

10. 5 个反模式¶

10.1 静默失败¶

// ❌
try { } catch (e) {}

swallow。

10.2 错误信息含敏感¶

// ❌
throw new Error(`API call failed: ${apiKey}`)

leak。

10.3 throw string¶

// ❌
throw 'error message'
// ✅
throw new Error('error message')

string。

10.4 catch 不处理¶

// ❌
try { ... } catch (e) {}  // 静默

noop。

10.5 error 不传给 log¶

// ❌
try { ... } catch (e) { return null }
// ✅
try { ... } catch (e) { logError(e); return null }

no log。

11. 速查：3 个错误判断¶

// 1. 业务错误
if (e instanceof McpAuthError) { ... }

// 2. session expired
if (isMcpSessionExpiredError(e)) { ... }

// 3. 用户取消
if (e instanceof AuthenticationCancelledError) { ... }

3 模式。

12. 速查：error class 树¶

Error
├── McpAuthError
├── McpSessionExpiredError
├── AuthenticationCancelledError
├── GcpCredentialsTimeoutError
├── FileTooLargeError
├── MaxFileReadTokenExceededError
├── TeleportOperationError (formattedMessage)
└── TelemetrySafeError_I_VERIFIED_*
    └── McpToolCallError_I_VERIFIED_*

8 个。

13. 总结¶

错误类 = 类型化错误处理。

核心： - 7+ 业务错误 - 2 Telemetry Safe - 5 处理模式 - 6 个 JSON-RPC 码 - 5 个 HTTP 码 - 商业级成熟度

下一步： - 看 error-codes.md - 看 error-handling-overview.md