错误码

本页汇总 WPF API 的错误表达方式，包括传输层 HTTP 状态码与业务层 code 错误码，帮助你快速定位问题。

一、两层错误模型

WPF API 的错误分为两层，排查时需同时关注：

层级	载体	含义
传输层	HTTP 状态码	请求是否被服务端正常接收与处理
业务层	响应体 `code` 字段	具体业务是否成功，`0` 为成功，非 `0` 为阻断

二、HTTP 状态码

状态码	含义	常见场景
200	请求成功	请求被正常处理（业务结果仍看 `code`）
400	请求错误	参数格式错误、请求体无法解析
401	未认证	Token 缺失、无效或已过期
403	无权限	已登录但无权操作目标资源
404	资源不存在	请求路径错误，或目标资源已删除
422	参数校验失败	必填字段缺失、字段类型或取值不合法
429	请求过于频繁	触发限流，需降低请求频率
500	服务器错误	服务端内部异常，请稍后重试或联系开发团队

三、通用业务错误码

响应体中的 code 字段。以下为跨模块通用的错误码框架：

code	含义	处理建议
0	成功	正常处理 `data`
400	参数错误	检查请求参数格式与取值
401	未登录 / Token 失效	重新登录获取 Token 后重试
403	无操作权限	确认当前用户是否有权访问该资源
404	资源不存在	检查业务标识（如编号、ID）是否正确
422	参数校验失败	补全必填字段，修正字段格式
429	请求过于频繁	增加请求间隔或退避重试
500	服务器内部错误	记录 `message` 并联系开发团队

四、模块特有错误码

各业务模块在通用错误码之外，可能返回模块特有的 code。

认证授权

code	含义	处理建议
10001	用户名或密码错误	核对登录凭据后重试
10002	账号已被禁用	联系管理员处理
10003	用户名已存在	更换用户名重新注册
20002	手机号已存在	更换手机号或直接登录
20004	旧密码错误	核对当前密码后重试

设备管理

code	含义	处理建议
30002	无设备查看权限 / 设备已离线	确认设备授权与在线状态
30003	无设备视频权限	申请对应设备的视频权限
30004	无设备控制权限	申请对应设备的控制权限
30005	指令不存在	核对指令 code 是否受设备类型支持
30006	不支持的设备类型	确认目标设备类型

音视频通话

code	含义	处理建议
41001	通话不存在	核对 `call_id`
41002	通话状态无效	按当前状态执行合法操作
41003	对方忙线	稍后重试
41004	当前用户非被叫方	仅被叫方可执行该操作
41005	当前用户非主叫方	仅主叫方可执行该操作
41006	已被其他终端接听	无需重复接听
41007 / 41008	通话已结束 / 已超时	重新发起通话
41009	Token 续期失败	重新发起或退出通话
41010	权限或关系校验失败	确认通话参与关系与好友状态
42201	频道名为空	补全 `channel_name`

GM 场景模块

code	含义	处理建议
400	无效的 seed_code	检查 seed_code 格式是否为合法短码
403	user_id 与 Token 不匹配	确认传入的 user_id 与登录用户一致
404	房间 / 快照不存在或已删除	提示用户核对房间编号或快照 ID

五、排查建议

先看 code 再看 message：code 定位错误类别，message 给出可读原因。
401 优先重登：Token 有效期有限，401 多数可通过重新登录解决。
422 检查请求体：逐项比对必填字段与类型，注意 JSON 结构层级。
500 保留现场：记录请求路径、请求体与响应 message，便于开发团队定位。