错误码参考

错误响应格式

所有 API 错误返回统一格式：

{
  "code": 40163,
  "msg": "code 已被消费",
  "data": null
}

• code: 1 表示成功
• code: 非1 表示失败，具体含义见下表

通用错误码

code	HTTP 状态	含义	排查建议
1	200	成功	-
0	200	通用失败	查看 msg 字段
-1	500	服务器内部错误	检查 PHP 错误日志
-2	503	服务维护中	等待恢复

鉴权错误（10xxx）

code	HTTP	含义	排查
10001	401	appid 不存在	检查 appid 是否正确
10002	401	appkey 错误	检查 appkey 是否正确
10003	401	签名错误	检查签名算法（字典序 + MD5）
10004	401	timestamp 过期	检查服务器时间，timestamp 5 分钟有效
10005	403	应用被禁用	联系管理员启用应用
10006	403	域名未授权	在 um_appdomain 表添加授权域名
10007	401	IP 不在白名单	检查应用 IP 白名单配置

OAuth 错误（40xxx）

code	HTTP	含义	排查
40101	400	不支持的登录类型	type 参数只能是 wx/alipay/qq/douyin/self
40102	400	redirect_uri 与配置不符	检查回调地址是否与 um_apps.url 一致
40103	400	state 校验失败	state 不匹配，可能 CSRF 攻击
40104	400	code 无效	code 已过期或不存在
40163	400	code 已被消费	同一 code 5 分钟内只能消费一次
40105	400	第三方平台授权失败	检查第三方平台配置（微信/支付宝等）
40106	400	获取用户信息失败	第三方 access_token 失效
40107	400	social_uid 不存在	二次查询的 social_uid 无效

Token 错误（50xxx）

code	HTTP	含义	排查
50001	401	token 不存在	token 已被删除或从未签发
50002	401	token 已过期	token 默认 7 天有效，需重新登录
50003	401	token 已被踢下线	单设备策略下被新登录踢掉
50004	403	token IP 不匹配	ip_bound 策略，当前 IP 与登录时不符
50005	403	token scope 不足	跨应用调用时 scope 不允许

用户错误（60xxx）

code	HTTP	含义	排查
60001	404	用户不存在	user_id 或 openid 错误
60002	400	手机号已注册	同一手机号不能重复注册
60003	400	邮箱已注册	同一邮箱不能重复注册
60004	400	验证码错误	检查短信/邮件验证码
60005	400	验证码已过期	验证码 5 分钟有效
60006	403	账号已被封禁	联系管理员解封

RBAC 错误（70xxx）

code	HTTP	含义	排查
70001	403	无权限访问	检查用户角色权限
70002	403	角色不存在	role_id 错误
70003	403	权限项不存在	perm_code 未注册到 um_perm_registry
70004	400	不能修改超级管理员	超级管理员角色不可删改

限流错误（90xxx）

code	HTTP	含义	排查
90001	429	请求过于频繁	触发限流，稍后重试
90002	429	登录失败次数过多	同一 IP 5 分钟内失败超 10 次
90003	429	接口调用超额	SaaS 套餐月调用量用尽

签名算法详解

// 1. 收集所有请求参数（除 sign 本身）
$params = [
    'appid' => '1000',
    'type'  => 'wx',
    'timestamp' => '1719500000',
    'state' => 'abc123',
    'redirect_uri' => 'https://your-app.com/callback',
];

// 2. 按 key 字典序升序排列
ksort($params);

// 3. 拼接成 key=val&key=val 格式
$parts = [];
foreach ($params as $k => $v) {
    $parts[] = "$k=$v";
}
$signStr = implode('&', $parts);

// 4. 末尾加上 appkey
$signStr .= '&appkey=' . $appkey;

// 5. MD5 取小写
$sign = md5($signStr);