API 错误码设计规范
错误码分类方案
一个良好的错误码分类系统可以帮助开发者快速定位问题来源。以下是一个推荐的错误码分类方案，采用5位数字编码，前两位表示模块/类别，后三位表示具体错误。
1. 基础分类结构
采用 AABBB 格式：
AA: 模块/大类代码 (01-99)BBB: 具体错误代码 (000-999)
2. 系统级错误码 (00xxx)
| 错误码范围 | 类别 | 示例代码 | 说明 |
|---|
| 00000 | 成功 | 00000 | 操作成功 |
| 00100-00199 | 系统通用错误 | 00101 | 系统内部错误 |
| 00200-00299 | 数据库错误 | 00201 | 数据库连接失败 |
| 00300-00399 | 缓存错误 | 00301 | Redis连接失败 |
| 00400-00499 | 文件/IO操作错误 | 00401 | 文件读写失败 |
| 00500-00599 | 网络通信错误 | 00501 | 第三方API调用失败 |
3. HTTP相关错误 (40xxx-50xxx)
| 错误码范围 | HTTP状态码对应 | 示例代码 | 说明 |
|---|
| 40000-40099 | 400 Bad Request | 40001 | 参数校验失败 |
| 40100-40199 | 401 Unauthorized | 40101 | 未授权/Token失效 |
| 40300-40399 | 403 Forbidden | 40301 | 权限不足 |
| 40400-40499 | 404 Not Found | 40401 | 资源不存在 |
| 40500-40599 | 405 Method Not Allowed | 40501 | 方法不允许 |
| 40800-40899 | 408 Request Timeout | 40801 | 请求超时 |
| 40900-40999 | 409 Conflict | 40901 | 资源冲突 |
| 42900-42999 | 429 Too Many Requests | 42901 | 请求过于频繁 |
50000-50099 | 500 Internal Server Error | 50001 | 服务器内部错误 |
4. 业务模块错误码 (10xxx-39xxx)
用户模块 (10xxx)
| 错误码范围 | 类别 | 示例代码 | 说明 |
|---|
| 10000-10099 | 用户通用错误 | 10001 | 用户不存在 |
| 10100-10199 | 注册相关错误 | 10101 | 用户名已存在 |
| 10200-10299 | 登录相关错误 | 10201 | 用户名或密码错误 |
| 10300-10399 | 权限相关错误 | 10301 | 无访问权限 |
| 10400-10499 | 资料修改错误 | 10401 | 手机号已被使用 |
订单模块 (11xxx)
| 错误码范围 | 类别 | 示例代码 | 说明 |
|---|
| 11000-11099 | 订单通用错误 | 11001 | 订单不存在 |
| 11100-11199 | 创建订单错误 | 11101 | 库存不足 |
| 11200-11299 | 支付相关错误 | 11201 | 支付失败 |
| 11300-11399 | 订单状态错误 | 11301 | 订单已取消 |
商品模块 (12xxx)
| 错误码范围 | 类别 | 示例代码 | 说明 |
|---|
| 12000-12099 | 商品通用错误 | 12001 | 商品不存在 |
| 12100-12199 | 库存相关错误 | 12101 | 库存不足 |
| 12200-12299 | 分类相关错误 | 12201 | 分类不存在 |
支付模块 (13xxx)
| 错误码范围 | 类别 | 示例代码 | 说明 |
|---|
| 13000-13099 | 支付通用错误 | 13001 | 支付渠道不可用 |
| 13100-13199 | 支付处理错误 | 13101 | 支付金额不符 |
| 13200-13299 | 退款相关错误 | 13201 | 退款失败 |
5. 第三方服务错误码 (50xxx-59xxx)
| 错误码范围 | 类别 | 示例代码 | 说明 |
|---|
| 50000-50099 | 短信服务错误 | 50001 | 短信发送失败 |
| 50100-50199 | 邮件服务错误 | 50101 | 邮件发送失败 |
| 50200-50299 | 云存储错误 | 50201 | 文件上传失败 |
| 50300-50399 | 地图服务错误 | 50301 | 地理编码失败 |
6. 客户端错误码 (60xxx-69xxx)
| 错误码范围 | 类别 | 示例代码 | 说明 |
|---|
| 60000-60099 | 客户端通用错误 | 60001 | 客户端版本过低 |
| 60100-60199 | 配置错误 | 60101 | 配置缺失 |
| 60200-60299 | 兼容性错误 | 60201 | 不支持的设备类型 |
7. 预留扩展空间
- 70xxx-89xxx: 为未来业务扩展预留
- 90xxx-99xxx: 为特殊场景预留
使用建议
- 模块划分：每个业务模块分配一个独立的AA前缀
- 错误码文档：维护详细的错误码文档，说明每个错误码的含义和解决方案
- 前后端协作：前后端团队共同遵守错误码规范
- 监控报警：根据错误码设置不同的监控报警级别
这种分类方式既保持了灵活性，又能清晰地标识错误来源，便于问题排查和系统监控。