错误规则

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

页面概览

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

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

规则测试器

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

使用方法

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

测试结果说明

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

规则列表

列表展示

每条规则显示以下信息：

默认规则

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

匹配方式

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

正则匹配（regex）

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

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

包含匹配（contains）

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

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

精确匹配（exact）

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

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

错误分类

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

添加规则

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

基本信息

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

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

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

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

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

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

响应覆写（高级选项）

勾选「启用响应覆写」后，可以配置：

覆写响应体

自定义匹配成功时返回给用户的错误响应，需符合 Claude API 错误格式：

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

覆写状态码

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

正则测试器

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

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

编辑规则

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

可编辑内容

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

删除规则

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

启用与禁用

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

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

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

刷新缓存

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

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

缓存统计

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

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

规则优先级

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

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

运行时行为

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

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

响应覆写处理

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

1. 验证覆写响应体格式是否合法
2. 移除 request_id 字段（会从上游注入）
3. 如果 message 为空，回退到原始错误消息
4. 验证状态码范围（400-599）

操作权限

最佳实践

规则配置建议

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

响应覆写建议

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

故障排查

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

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

相关功能

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