SuperAPI AI Directory

error-handling

General & other

View repository

Updated 10-16 08:49

About this skill

Error Code Design

Reference sources:RFC 7807 Problem Details, Stripe / GitHub API error specifications

Applicable scenarios

  • API error response structure design
  • Error code system establishment
  • Error handling guide for callers
  • Debugging and observability

Core principles

1. 错误必须能指导调用方恢复
   不只是说"出错了",要说"怎么办"
  1. Distinguish HTTP status codes from business error codes HTTP: protocol-level errors (authentication, format, server) Business codes: business logic-level errors (insufficient inventory, state not allowed)

  2. Do not wrap errors in 200 Breaks HTTP semantics

  3. Do not leak sensitive information Error messages must not expose internal architecture


## 错误响应标准结构(RFC 7807)

```json
{
  "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
    }
  ]
}

Simplified structure (recommended)

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

Required error fields

1. code(业务错误码)
   - 字符串,下划线命名
   - 例:insufficient_funds / invalid_email / order_not_found

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

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

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

HTTP status codes vs business error codes

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"

Error code naming conventions

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

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

  ❌ ERR001(无语义)
  ❌ Error.InsufficientFunds(驼峰)
  ❌ NSF(缩写难懂)

Form validation errors (multiple fields)

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
    }
  ]
}

Rate limiting errors (required fields)

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"
}

Error code table

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

| 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 | 资源已删除 | "资源不存在" | 返回列表 | ❌ |

Workflow

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

Quality self-check

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

Common pitfalls

  1. Wrapping errors in 200——HTTP 200 + success: false in the body
  2. Error messages only in English——Users of Chinese projects cannot understand them
  3. Missing trace_id——Cannot troubleshoot
  4. Rate limiting returns 429 but no Retry-After——The client does not know when to retry
  5. Validation failure returns only 1 item——There are 5 error fields but only 1 is seen
  6. Error messages expose technical details——"Database connection failed"
  7. Do not distinguish 401 from 403——Logged in but without permission returns 401
  8. 404 hides permissions(for privacy considerations) but is inconsistent

Supporting templates

  • templates/error-code-template.md — Error code table + error response structure template

Collaboration with other skills

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

平行:
  auth-permission → 401/403 错误细分
  idempotency-retry → 重试相关错误(409/429)

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