name	error-handling
description	设计 API 错误码和错误结构时使用。适用于错误响应规范、调用方错误处理、调试可观测。优先使用 RFC 7807 Problem Details + 业务错误码 + 调用方处理建议。

错误码设计

参考来源：RFC 7807 Problem Details、Stripe / GitHub API 错误规范

适用场景

API 错误响应结构设计
错误码体系建立
给调用方的错误处理指南
调试和可观测性

核心原则

1. 错误必须能指导调用方恢复
   不只是说"出错了"，要说"怎么办"

2. 区分 HTTP 状态码和业务错误码
   HTTP：协议层级错误（认证、格式、服务器）
   业务码：业务逻辑层级错误（库存不足、状态不允许）

3. 不要 200 包装错误
   破坏 HTTP 语义

4. 不要泄露敏感信息
   错误信息不能暴露内部架构

错误响应标准结构（RFC 7807）

{
  "type": "https://api.example.com/errors/insufficient_funds",
  "title": "Insufficient Funds",
  "status": 402,
  "detail": "Your account balance is insufficient for this operation.",
  "instance": "/orders/123",
  "code": "insufficient_funds",
  "trace_id": "req_abc123",
  "errors": [
    {
      "field": "amount",
      "message": "Amount exceeds available balance",
      "current_balance": 50.00,
      "required": 100.00
    }
  ]
}

简化结构（推荐）

{
  "code": "insufficient_funds",
  "message": "Your account balance is insufficient",
  "trace_id": "req_abc123",
  "details": {
    "current_balance": 50.00,
    "required": 100.00
  }
}

错误必备字段

1. code（业务错误码）
   - 字符串，下划线命名
   - 例：insufficient_funds / invalid_email / order_not_found

2. message（用户可见信息）
   - 简短可读
   - 中文项目用中文
   - 不暴露技术细节

3. trace_id（追踪 ID）
   - 用于客服 / 工程师查日志
   - 必须有

4. details（详细信息，可选）
   - 字段级错误（表单校验）
   - 上下文数据（库存数量、当前余额）

HTTP 状态码 vs 业务错误码

HTTP 状态码（粗粒度）：
  400 Bad Request - 请求格式错误
  401 Unauthorized - 未认证
  403 Forbidden - 无权限
  404 Not Found - 资源不存在
  409 Conflict - 冲突
  422 Unprocessable - 校验失败
  429 Too Many Requests - 限流

业务错误码（细粒度）：
  在同一个 HTTP 状态码下区分具体原因

  HTTP 422 + code:
    - "invalid_email"
    - "weak_password"
    - "username_taken"

  HTTP 409 + code:
    - "duplicate_order"
    - "concurrent_modification"
    - "resource_locked"

错误码命名规范

风格：snake_case
长度：≤ 30 字符
结构：[资源]_[原因] 或 [原因]

示例：
  ✅ insufficient_funds
  ✅ order_not_found
  ✅ invalid_email
  ✅ rate_limit_exceeded
  ✅ payment_method_required

  ❌ ERR001（无语义）
  ❌ Error.InsufficientFunds（驼峰）
  ❌ NSF（缩写难懂）

表单校验错误（多字段）

HTTP 422 Unprocessable Entity

{
  "code": "validation_failed",
  "message": "Request validation failed",
  "trace_id": "req_abc123",
  "errors": [
    {
      "field": "email",
      "code": "invalid_format",
      "message": "邮箱格式不正确"
    },
    {
      "field": "password",
      "code": "too_short",
      "message": "密码至少 8 位",
      "min_length": 8,
      "actual_length": 5
    }
  ]
}

限流错误（必备字段）

HTTP 429 Too Many Requests
Retry-After: 60

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "trace_id": "req_abc123",
  "limit": 100,
  "remaining": 0,
  "reset_at": "2026-01-15T10:31:00Z"
}

错误码表

## 错误码表：[模块名]

| HTTP | 业务码 | 触发条件 | 用户提示 | 调用方处理 | 可重试 |
|------|--------|---------|---------|-----------|--------|
| 400 | invalid_email | 邮箱格式错误 | "邮箱格式不正确" | 检查并提示用户 | ❌ |
| 401 | token_expired | Token 过期 | "登录已过期" | 引导重新登录 | ❌ |
| 401 | token_invalid | Token 无效 | "登录信息异常" | 引导重新登录 | ❌ |
| 403 | permission_denied | 无权限 | "无权访问" | 提示联系管理员 | ❌ |
| 404 | order_not_found | 订单不存在 | "订单不存在" | 检查 ID 或刷新列表 | ❌ |
| 409 | duplicate_order | 重复创建 | "订单已存在" | 提示重复，跳转到已有订单 | ❌ |
| 422 | validation_failed | 字段校验失败 | 见 errors 字段 | 高亮错误字段 | ❌ |
| 429 | rate_limit_exceeded | 调用过频 | "请稍后再试" | 按 Retry-After 等待重试 | ✅ |
| 500 | internal_error | 服务异常 | "系统异常，请稍后" | 显示通用错误 + 重试 | ✅ |
| 503 | service_unavailable | 服务不可用 | "服务繁忙" | 显示通用错误 + 重试 | ✅ |
| 402 | insufficient_funds | 余额不足 | "余额不足" | 引导充值 | ❌ |
| 409 | order_already_paid | 订单已支付 | "订单已支付" | 跳转到订单详情 | ❌ |
| 410 | resource_deleted | 资源已删除 | "资源不存在" | 返回列表 | ❌ |

工作流程

1. 列出端点清单
2. 对每个端点列出可能的失败场景
3. 对每个失败场景：
   - 选 HTTP 状态码
   - 设计业务错误码（snake_case）
   - 写用户可见消息
   - 写调用方处理建议
   - 标注是否可重试
4. 输出错误码表
5. 在 OpenAPI 中定义错误响应 Schema

质量自检

□ HTTP 状态码使用正确
□ 业务错误码命名规范（snake_case）
□ 每个错误码有触发条件说明
□ 每个错误码有用户提示
□ 每个错误码有调用方处理建议
□ 是否标注了可重试
□ 表单校验返回字段级错误
□ 限流返回 Retry-After 和限额信息
□ 错误信息不泄露内部架构
□ 所有错误都有 trace_id

常见坑

200 包装错误——HTTP 200 + body 里 success: false
错误信息只有英文——中文项目用户看不懂
trace_id 缺失——无法排查
限流返回 429 但没 Retry-After——客户端不知道何时重试
校验失败只返回 1 条——有 5 个错误字段只看到 1 个
错误信息暴露技术细节——"Database connection failed"
不区分 401 和 403——已登录但无权限返回 401
404 隐藏权限（隐私考虑）但不一致

配套模板

templates/error-code-template.md — 错误码表 + 错误响应结构模板

与其他 skill 的协作

上游：
  endpoint-design → 端点清单
  request-response → 校验规则触发的错误

平行：
  auth-permission → 401/403 错误细分
  idempotency-retry → 重试相关错误（409/429）

下游：
  openapi-mock → 错误响应写入 OpenAPI
  转交前端 → 错误处理实现
  转交 QA → 错误场景测试