「短网址服务」错误码规范

短网址服务错误码规范（整数版，10/11/12/13/14 前缀）

1. 错误码设计规则

  • 格式：XXYYZZ

    • XX：模块前缀（两位整数）
    • YY：子分类（可选）
    • ZZ：错误序号（递增）

2. 模块划分

  • 10xxxx → 通用错误（Common）
  • 11xxxx → 用户与认证（Auth/User）
  • 12xxxx → 短链服务（URL/Shorten）
  • 13xxxx → API & Dashboard
  • 14xxxx → 统计与报表（Stats/Report）

3. 错误码表

通用错误（10xxxx）

错误码 HTTP 状态 描述 前端提示
100001 400 参数不合法 输入有误，请检查后重试
100002 429 请求过于频繁 操作过于频繁，请稍后再试
100003 500 系统内部错误 系统开小差了，请稍后再试

用户与认证（11xxxx）

错误码 HTTP 状态 描述 前端提示
110001 400 邮箱格式不合法 邮箱格式错误，请重新输入
110002 409 邮箱已注册 该邮箱已被注册，请直接登录
110003 401 登录失败（账号/密码错误） 邮箱或密码不正确，请重试
110004 401 Token 无效或过期 登录已过期，请重新登录
110005 403 权限不足 您没有权限执行此操作
110006 400 Refresh Token 无效 登录状态已失效，请重新登录

短链服务（12xxxx）

错误码 HTTP 状态 描述 前端提示
120001 400 长链格式不合法 链接格式不正确，请输入有效网址
120002 400 长链过长 链接过长，请缩短后重试
120003 403 URL 在黑名单中 该链接无法生成短网址
120004 409 自定义短码已存在 短码已被使用，请更换后重试
120005 404 短链不存在 短链不存在或已被删除
120006 410 短链已过期 短链已过期，请重新生成
120007 500 短链生成失败 短链生成失败，请稍后再试

API & Dashboard（13xxxx）

错误码 HTTP 状态 描述 前端提示
130001 401 API Key 无效 API Key 无效，请检查配置
130002 403 API Key 权限不足 API Key 权限不足，请联系管理员
130003 429 API 调用超限 API 调用次数超出限制，请稍后再试
130004 404 短链记录未找到 未找到相关短链记录
130005 400 参数错误（分页/筛选非法） 请求参数错误，请检查后重试

统计与报表（14xxxx）

错误码 HTTP 状态 描述 前端提示
140001 404 没有找到统计数据 暂无统计数据
140002 400 时间区间不合法 时间范围选择有误
140003 500 聚合统计失败 数据统计失败，请稍后再试

4. 返回示例

成功

1
2
3
4
5
6
7

{
  "code": 0,
  "message": "success",
  "data": {
    "short_url": "https://s.io/abc123"
  }
}

短码冲突（120004）

1
2
3
4
5

{
  "code": 120004,
  "message": "Custom short code already exists",
  "data": null
}

Token 过期（110004）

1
2
3
4
5

{
  "code": 110004,
  "message": "Token expired or invalid",
  "data": null
}

API 超限（130003）

1
2
3
4
5

{
  "code": 130003,
  "message": "API rate limit exceeded",
  "data": null
}

接口与错误码映射表

1. 用户认证模块

POST /api/auth/register

  • 成功 → code = 0

  • 可能错误码：

    • 100001 参数不合法（邮箱/密码缺失）
    • 110001 邮箱格式不合法
    • 110002 邮箱已注册
    • 100003 系统内部错误

POST /api/auth/login

  • 成功 → code = 0

  • 可能错误码：

    • 100001 参数不合法（邮箱/密码缺失）
    • 110003 登录失败（账号/密码错误）
    • 100003 系统内部错误

POST /api/auth/refresh

  • 成功 → code = 0

  • 可能错误码：

    • 110006 Refresh Token 无效
    • 110004 Token 过期/无效
    • 100003 系统内部错误

POST /api/auth/logout

  • 成功 → code = 0

  • 可能错误码：

    • 110004 Token 过期/无效
    • 100003 系统内部错误

2. 短链服务模块

POST /api/shorten

  • 成功 → code = 0

  • 可能错误码：

    • 100001 参数不合法（长链缺失）
    • 120001 长链格式不合法
    • 120002 长链过长
    • 120003 URL 在黑名单中
    • 120004 自定义短码已存在
    • 100003 系统内部错误

GET /{short_code} （跳转接口）

  • 成功 → HTTP 302 跳转

  • 可能错误码：

    • 120005 短链不存在
    • 120006 短链已过期
    • 100003 系统内部错误

DELETE /api/{short_code}

  • 成功 → code = 0

  • 可能错误码：

    • 110005 权限不足（试图删除非本人短链）
    • 120005 短链不存在
    • 120006 短链已过期
    • 100003 系统内部错误

GET /api/info/{short_code}

  • 成功 → code = 0

  • 可能错误码：

    • 120005 短链不存在
    • 120006 短链已过期
    • 100003 系统内部错误

GET /api/list?page=1&size=20

  • 成功 → code = 0

  • 可能错误码：

    • 100001 参数不合法（分页参数错误）
    • 100003 系统内部错误

3. API & Dashboard 模块

GET /api/dashboard/urls

  • 成功 → code = 0

  • 可能错误码：

    • 110004 Token 无效/过期
    • 130005 参数错误（筛选非法）
    • 100003 系统内部错误

POST /api/dashboard/apikeys

  • 成功 → code = 0

  • 可能错误码：

    • 110004 Token 无效/过期
    • 100001 参数不合法
    • 100003 系统内部错误

DELETE /api/dashboard/apikeys/{id}

  • 成功 → code = 0

  • 可能错误码：

    • 110005 权限不足
    • 130004 API Key 未找到
    • 100003 系统内部错误

4. 统计与报表模块

GET /api/stats/{short_code}

  • 成功 → code = 0

  • 可能错误码：

    • 120005 短链不存在
    • 140001 没有找到统计数据
    • 140002 时间区间不合法
    • 100003 系统内部错误

GET /api/stats/trends

  • 成功 → code = 0

  • 可能错误码：

    • 140002 时间区间不合法
    • 100003 系统内部错误

5. API 限流场景（所有接口通用）

  • 100002 请求过于频繁
  • 130003 API 调用超限