错误规则

错误规则是 Claude Code Hub 的智能错误处理功能，用于识别和分类上游 API 返回的错误消息。通过配置错误规则，系统可以智能判断哪些错误应该重试、哪些错误应该直接返回给用户，从而提升用户体验和系统稳定性。

页面概览

错误规则管理页面位于 设置 > 错误规则 (/settings/error-rules)，提供以下功能：

• 规则测试器：实时测试错误消息是否匹配规则
• 规则列表：展示所有已配置的错误规则及其状态
• 添加规则：创建自定义错误规则
• 刷新缓存：同步默认规则并重新加载缓存

规则测试器

规则测试器位于页面顶部，用于验证错误消息是否能被正确匹配。

使用方法

1. 在「测试消息」输入框中输入要测试的错误消息
2. 点击「测试」按钮
3. 查看匹配结果

测试结果说明

测试结果会显示以下信息：

规则列表

列表展示

每条规则显示以下信息：

默认规则

系统预置了以下默认错误规则，覆盖常见的不可重试错误场景：

预设错误规则

Claude Code Hub 内置了一套预设错误规则（DEFAULT_ERROR_RULES），覆盖常见的不可重试错误场景。这些规则在系统启动时自动同步到数据库，确保用户开箱即用。

预设规则类型

系统预设规则覆盖以下错误类别：

预设规则详情

以下是 v0.3.30 版本中包含的完整预设规则列表：

同步策略

预设规则采用「用户自定义优先」的同步策略，确保用户的修改不会被覆盖：

同步时机

• 系统启动时：自动执行 syncDefaultErrorRules() 同步预设规则
• 手动刷新：点击「刷新缓存」按钮时同步最新预设规则

编辑默认规则的行为

当用户编辑默认规则的匹配模式或分类时，系统会自动将 isDefault 标记为 false，将其转换为用户自定义规则。这样可以：

1. 保留用户的修改不被后续同步覆盖
2. 允许用户完全控制该规则的配置
3. 系统升级时不会丢失用户的自定义内容

匹配优先级

错误规则检测器按照性能优先的顺序进行匹配：

错误消息输入
     ↓
1. 包含匹配（contains）
   - 遍历所有包含规则
   - 检查 message.includes(pattern)
   - 大小写不敏感
     ↓ 未命中
2. 精确匹配（exact）
   - 使用 HashMap O(1) 查找
   - 匹配 message.trim() === pattern
   - 大小写不敏感
     ↓ 未命中
3. 正则匹配（regex）
   - 依次执行正则表达式
   - 大小写不敏感（/i 标志）
   - 带 ReDoS 安全检测
     ↓
返回匹配结果

手动同步预设规则

除了系统自动同步外，也可以通过命令行手动同步：

bun run scripts/init-error-rules.ts

执行后会显示同步统计：

Syncing default error rules...
Default error rules synced: 5 inserted, 10 updated, 2 skipped, 1 deleted

• inserted：新增的规则数量
• updated：更新的默认规则数量
• skipped：跳过的用户自定义规则数量
• deleted：删除的过期默认规则数量

匹配方式

错误规则支持三种匹配方式：

正则匹配（regex）

使用正则表达式进行模式匹配，功能最强大但性能相对较慢。

• 适用场景：复杂的模式匹配、需要捕获多种变体的错误消息
• 示例：prompt is too long.*(tokens.*maximum|maximum.*tokens)
• 注意事项：
  • 系统会自动进行 ReDoS（正则表达式拒绝服务）风险检测
  • 存在风险的正则表达式会被拒绝保存

包含匹配（contains）

检查错误消息是否包含指定文本，大小写不敏感。

• 适用场景：简单的关键词匹配
• 示例：blocked by
• 性能优势：比正则匹配更快

精确匹配（exact）

检查错误消息是否完全等于指定文本，大小写不敏感。

• 适用场景：需要精确匹配特定错误消息
• 示例：rate limit exceeded
• 性能优势：使用 Hash 查找，性能最优

错误分类

错误规则使用分类（Category）对错误进行归类，便于统计和管理：

添加规则

点击页面右上角的「添加规则」按钮，打开规则创建对话框。

基本信息

1. 匹配模式（必填）：用于匹配错误消息的模式

   • 支持正则表达式语法
   • 系统会自动验证正则表达式的有效性和安全性

2. 错误分类（必填）：选择错误所属的业务类别

   • 从预定义的分类列表中选择

3. 描述（可选）：规则的说明文字

   • 建议填写，便于后续维护

响应覆写（高级选项）

勾选「启用响应覆写」后，可以配置自定义错误响应和状态码。

覆写响应体

自定义匹配成功时返回给用户的错误响应。系统支持三种 API 格式，点击「使用模板」下拉菜单可快速选择：

Claude API 格式

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "您的自定义错误消息"
  }
}

• 顶层 type 必须为 "error"
• error.type 为错误类型标识（如 invalid_request_error、authentication_error）
• error.message 为人类可读的错误描述

Gemini API 格式

{
  "error": {
    "code": 400,
    "message": "您的自定义错误消息",
    "status": "INVALID_ARGUMENT"
  }
}

• error.code 为数字类型的错误码
• error.status 为状态标识（如 INVALID_ARGUMENT、PERMISSION_DENIED）
• error.details 为可选数组，包含详细错误信息

OpenAI API 格式

{
  "error": {
    "message": "您的自定义错误消息",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

• error.type 为错误类型（如 invalid_request_error、rate_limit_error）
• error.param 为可选字段，指示出错的参数名
• error.code 为可选字段，错误代码

覆写状态码

自定义 HTTP 响应状态码，取值范围 400-599。留空则使用上游原始状态码。

• 系统在运行时会校验状态码范围，超出范围的配置将被忽略
• 状态码覆写可以独立使用，无需同时配置响应体覆写

正则测试器

对话框底部会显示正则表达式测试器，可以实时验证正则表达式是否正确：

1. 输入测试文本
2. 查看匹配结果（高亮显示匹配部分）

编辑规则

点击规则行右侧的编辑图标（铅笔图标）可修改规则配置。

可编辑内容

• 自定义规则：所有字段均可编辑
• 默认规则：仅可编辑描述、响应覆写和状态码覆写

删除规则

点击规则行右侧的删除图标（垃圾桶图标）可删除规则。

启用与禁用

每条规则右侧有一个开关，用于快速启用或禁用规则。

• 启用：规则参与错误匹配检测
• 禁用：规则被跳过，不参与匹配

禁用规则后，相关错误将走默认处理流程（可能触发重试）。

刷新缓存

点击页面右上角的「刷新缓存」按钮可以：

1. 同步默认规则：将代码中的最新默认规则同步到数据库
2. 重新加载缓存：刷新内存中的规则缓存

缓存统计

按钮右侧显示当前缓存的规则总数。悬停可查看详细统计：

• 正则规则数量
• 包含规则数量
• 精确规则数量

规则优先级

规则按照以下顺序进行匹配：

1. 启用状态：禁用的规则不参与匹配
2. 匹配类型：包含 → 精确 → 正则（性能优先）
3. 优先级字段：数值越小优先级越高

运行时行为

当 API 请求返回错误时，系统会按以下流程处理：

上游返回错误
     ↓
错误规则检测器匹配
     ↓
├── 命中规则 → 跳过重试，直接返回（可应用覆写）
└── 未命中 → 按熔断器/重试逻辑处理

异步规则检测机制

错误规则检测器采用懒加载和异步初始化策略，确保在数据库连接未就绪时不会阻塞系统启动。

懒加载机制

• 规则在首次检测时才从数据库加载，而非应用启动时
• 避免在数据库迁移未完成时过早加载导致错误
• 加载成功后缓存在内存中，后续检测直接使用缓存

Promise 合并防竞态

当多个并发请求同时触发首次加载时，系统使用 Promise 合并模式：

• 只有第一个请求会实际执行数据库查询
• 其他并发请求等待同一个 Promise 结果
• 避免重复加载造成的资源浪费和数据不一致

detectAsync 方法

推荐使用 detectAsync 方法进行错误检测，该方法会自动确保规则已加载：

// 推荐：异步检测，确保规则已加载
const result = await errorRuleDetector.detectAsync(errorMessage);

// 不推荐：同步检测，规则可能未加载完成
const result = errorRuleDetector.detect(errorMessage);

如果使用同步 detect 方法时规则尚未加载，系统会记录警告日志但不会阻塞，返回结果可能不完整。

规则检测顺序

检测器按照性能优先的顺序匹配规则：

• 一旦命中任意规则，立即返回结果，不再继续匹配
• 建议优先使用包含匹配和精确匹配以获得更好的性能

数据库异常保护

当数据库连接异常时，检测器采用降级策略：

• 加载失败时不抛出异常，只记录错误日志
• 保留现有内存缓存（如果有），保持系统可用
• 下次检测时自动重试加载
• 一旦成功加载，后续不再重试（直到服务重启或缓存刷新）

响应覆写处理

当命中规则且配置了响应覆写时：

1. 验证覆写响应体格式是否合法（支持 Claude/Gemini/OpenAI 三种格式）
2. 自动检测响应格式类型并记录日志
3. 如果 message 为空，回退到原始错误消息
4. 验证状态码范围（400-599），超出范围则使用上游原始状态码

格式自动检测

系统会自动识别覆写响应的格式类型：

响应体大小限制

覆写响应体最大支持 10KB。超出限制的配置将在保存时被拒绝。

操作权限

最佳实践

规则配置建议

1. 善用默认规则：默认规则已覆盖常见场景，通常无需额外配置
2. 优先使用简单匹配：包含匹配和精确匹配性能更好，优先考虑
3. 正则表达式要精简：避免过于复杂的正则，防止性能问题
4. 测试后再启用：创建规则后务必使用测试器验证

响应覆写建议

1. 统一错误格式：使用覆写功能统一不同供应商的错误响应格式
2. 友好错误消息：将技术性错误消息转换为用户友好的提示
3. 保留调试信息：生产环境可考虑简化消息，开发环境保留详细信息

故障排查

如果错误规则未按预期工作：

1. 检查规则是否启用：确认规则状态开关已打开
2. 使用测试器验证：输入实际错误消息测试是否匹配
3. 检查正则表达式：确保正则语法正确，无 ReDoS 风险
4. 刷新缓存：点击刷新缓存按钮确保最新规则生效
5. 查看警告信息：测试器会显示配置问题的警告

相关功能

• 高可用机制 - 了解熔断器和重试机制
• 供应商管理 - 配置供应商的熔断参数
• 日志查询 - 查看错误请求的详细日志