参数校验错误
{
"code": 10001,
"message": "参数校验失败",
"data": {
"errors": [
{
"field": "email",
"message": "邮箱格式不正确",
"value": "invalid-email"
},
{
"field": "password",
"message": "密码长度至少 8 位",
"value": "123"
}
]
}
}
field
出错字段名，前端可定位表单
message
用户友好的错误描述
value
客户端提交的值（可选）
业务错误
{
"code": 20001,
"message": "余额不足",
"data": {
"current_balance": 50.00,
"required_amount": 99.00,
"shortfall": 49.00,
"suggestion": "请充值后重试"
}
}
✓ 返回当前状态数据，便于前端展示
✓ 提供 suggestion 给出解决建议
✓ 数据结构化，前端可灵活展示
错误码分层设计
{{ layer.range }}
{{ layer.name }}
示例：{{ layer.example }}
{{ layer.desc }}
错误码从外到内：系统 → 服务 → 业务 → 认证 → 参数
HTTP 状态码 vs 业务状态码
HTTP 状态码
传输层状态
2xx
请求成功
4xx
客户端错误
5xx
服务端错误
→
业务状态码
业务层状态
0
业务成功
1xxxx
参数错误
2xxxx
业务错误
HTTP 200 + 业务错误码 是业界主流做法
常见错误码示例
{{ item.code }}
{{ item.message }}