27 错误码大全

全站接口走统一返回（app\common\ApiResponse），status 字段沿用 HTTP 语义。本篇汇总所有状态码与典型业务错误信息。

统一返回结构

{ "status": 200, "msg": "ok", "data": {} }

字段	类型	说明
status	int	状态码（见下），成功为 200
msg	string	可读信息（成功多为 ok/success）
data	object/array	业务数据；列表为 { list, total }

注意：HTTP 响应码通常为 200，业务结果以 body 内 status 为准。前端应判断 status 而非仅 HTTP 状态。

状态码总表

status	含义	典型场景
200	成功	正常返回
400	请求错误/参数非法/业务校验失败	缺参数、优惠码无效、余额不足、账号或密码错误
401	未登录/令牌失效/凭据错误	无 token、JWT 过期、账号不存在或状态异常、API 密钥无效
403	无权限/被禁止	无模块权限、系统已安装、IP 不在白名单
404	资源不存在	各类「XX 不存在」
502	上游/网关错误	开通模块或上游返回失败
500	服务器内部错误	未捕获异常（APP_DEBUG=false 时为通用错误页）

401 鉴权类（典型 msg）

msg	来源
未登录	会员中心/后台缺 token
账号不存在	当前 token 对应用户/管理员不存在
未登录或令牌过期	开放 API v1 鉴权失败
账号不存在或状态异常	开放 API 登录：用户非 active
API密钥无效或未启用	开放 API 登录：密钥错误/停用
账号或密码错误	后台/会员登录失败（400）

403 权限类

msg	来源
系统已安装	安装向导接口在已安装后被调用（setup）
IP 不在白名单内: <ip>	开放 API 登录命中 IP 白名单限制
无 msg / 通用	后台访问无对应模块权限（AdminAuth 拦截）

404 资源不存在（按域汇总）

域	典型 msg
商品	商品不存在 / 商品不存在或已下架 / 商品组不存在
选项	选项组不存在 / 选项不存在 / 子选项不存在
客户/服务	客户不存在 / 服务不存在 / 账号不存在
财务	订单不存在 / 账单不存在 / 网关不存在
营销	优惠码不存在 / 横幅不存在
支持	工单不存在 / 部门不存在 / 公告不存在 / 文章不存在 / 分类不存在 / 记录不存在
上下游	上游不存在 / 密钥不存在 / 模块不存在
系统	员工不存在 / 角色不存在

400 业务校验（示例）

msg	来源
请提供账号与API密钥	开放 API 登录缺参
该商品不是上游代理商品	刷新上游上下文时商品类型不符
下单/续费校验失败信息	OrderService/InvoiceService 抛 InvalidArgumentException，原样透出

502 上游/网关

msg	来源
模块返回的 result.message	后台手动开通（Host::provision）调用开通模块失败时透出上游原因

异常透出原则

• 业务异常（如下单参数错误）：服务层抛 \InvalidArgumentException，控制器捕获后以 400 + 原始信息返回；
• 系统/上游异常（如更新、开通）：抛 \RuntimeException，携带明确原因原样透出，不静默兜底；
• 未捕获异常：由 app\ExceptionHandle 处理，APP_DEBUG=true 显示堆栈，生产显示通用错误页（config/app.php 的 error_message）。

前端处理建议

const res = await request.post('/admin/xxx', payload)
if (res.status !== 200) {
  Message.error(res.msg || '操作失败')
  // 401 → 跳登录；403 → 提示无权限
  return
}
// 使用 res.data

---

返回 20 开发文档（总览）