错误码参考

1. 错误码体系

所有 API 响应均包含统一错误码，格式为 5 位十进制数字。

范围	含义	说明
0	成功	请求正常处理
1xxx	业务错误	业务逻辑相关的预期内失败
2xxx	内容/数据错误	数据校验、内容合规等
3xxx	客户端通用错误	请求参数、格式、配额等
4xxx	认证与权限	身份验证或访问控制失败
5xxx	服务端错误	系统内部异常

成功响应示例：{ "code": 0, "message": "success", "data": { ... } }

错误响应示例：{ "code": 40000, "message": "参数 'name' 不能为空", "data": null }

2. 认证相关（4xx00）

错误码	HTTP 状态码	消息模板	触发场景	建议操作
40100	401	未提供认证凭据	请求头缺少 Authorization	检查请求是否携带 Bearer <token>
40101	401	认证凭据无效或已过期	Token 格式错误、签名无效或已过期	重新获取有效 Token
40102	401	认证凭据已被吊销	Token 已被主动撤销或列入黑名单	联系管理员或重新登录
40103	401	不支持的认证方式	使用了系统未启用的认证方案	改用支持的认证方式（如 Bearer）

3. 权限相关（4xx03）

错误码	HTTP 状态码	消息模板	触发场景	建议操作
40300	403	无权访问该资源	当前身份不具备目标资源的访问权限	确认角色权限或联系管理员
40301	403	操作被策略禁止	请求触发了访问控制策略限制（如 IP 白名单）	检查账号策略配置
40302	403	账户已禁用	账户被管理员冻结或停用	联系管理员申请恢复
40303	403	超出调用配额	API 调用次数或频率超过限制	等待配额重置或申请扩容

4. 参数相关（3xx00–3xx01）

错误码	HTTP 状态码	消息模板	触发场景	建议操作
40000	400	请求参数校验失败	必填字段缺失、参数类型错误或格式不符合规范	核对 API 文档中的参数定义
40001	400	参数值超出允许范围	数值超出最大/最小值、字符串超长等	调整参数值至合法范围
40002	400	请求体格式错误	JSON 解析失败或 Content-Type 不正确	检查 JSON 语法和 Content-Type 头
40010	400	分页参数无效	page ≤ 0 或 page_size 超出上限	使用合法分页值（如 page≥1, page_size≤100）

5. 资源相关（3xx04）

错误码	HTTP 状态码	消息模板	触发场景	建议操作
40400	404	资源不存在	请求的资源 ID 无效或已被删除	确认资源 ID 是否正确
40401	404	资源类型不存在	请求的端点或资源类型不被系统识别	检查请求路径和资源类型名称
40402	404	关联资源不存在	请求中引用的外键资源缺失	先创建关联资源或修正引用 ID

6. 冲突相关（3xx09）

错误码	HTTP 状态码	消息模板	触发场景	建议操作
40900	409	资源已存在（唯一约束冲突）	创建时与已有资源的唯一字段重复	更换唯一标识或更新已有资源
40901	409	版本冲突（乐观锁失败）	资源的 version 字段与服务端不匹配	重新获取最新版本后重试
40902	409	状态冲突	当前资源状态不允许执行该操作	先将资源转换到允许的状态

7. 服务端错误（5xxxx）

错误码	HTTP 状态码	消息模板	触发场景	建议操作
50000	500	服务器内部错误	未预期的服务端异常	稍后重试；如持续出现请联系技术支持
50001	502	上游服务不可用	依赖的外部服务调用失败或超时	稍后重试；检查依赖服务状态
50002	503	服务暂时不可用	系统维护中或过载降级	等待后重试，指数退避
50003	504	上游服务超时	依赖的外部服务响应超时	简化请求或稍后重试

8. HTTP 状态码映射总览

HTTP 状态码	错误码范围	含义
200	0	成功
400	40000–40099	请求参数错误
401	40100–40199	认证失败
403	40300–40399	权限不足
404	40400–40499	资源未找到
409	40900–40999	资源冲突
429	40303	请求频率超限
500	50000	服务端内部错误
502	50001	上游服务不可用
503	50002	服务不可用
504	50003	上游服务超时