错误码应使用带前缀的字符串枚举而非数字，如"auth_token_expired"，以提升可读性、可搜索性和版本可控性，并避免歧义与硬编码问题。
错误码该不该用数字？
数字错误码看似直观，但实际协作中极易引发歧义——4001 到底是“参数缺失”还是“用户未登录”？不同模块各自定义，前端硬编码比对，后期改一个码就得全链路排查。更麻烦的是，数字无法携带语义，日志里只看到 error_code=5003，不翻文档根本不知道发生了什么。
推荐做法：全部使用带前缀的字符串枚举，例如 "auth_token_expired"、"payment_amount_too_low"。这样既可读、可搜索、可版本化，又避免整数溢出或类型混淆（比如 Python 里误把 int 当 str 传给 JSON 序列化）。
常见错误现象：
- 后端返回
4001，前端写死if code === 4001，结果某次发布悄悄改成4002，接口直接挂掉 - 错误码混用 HTTP 状态码含义（如用
500表示“余额不足”，掩盖真实服务异常）
如何组织错误码常量？
别散落在各个 view 或 service 文件里。所有错误码必须集中定义、唯一来源，否则复制粘贴一次，就埋下三个不一致的坑。
立即学习“Python免费学习笔记（深入）”；
实操建议：
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 新建
errors.py，用Enum定义（Python 3.4+），每个成员值为元组：("auth_token_expired", "Token 已过期，请重新登录") - 对外只暴露
.code和.message属性，禁止直接用字符串字面量 - 加一层
make_error_response()工具函数，统一包装成{"code": "...", "message": "...", "data": null}结构 - 如果支持多语言，
message字段留空，靠前端根据code查 i18n 表，后端绝不拼接中文
HTTP 状态码和业务错误码怎么配合？
HTTP 状态码不是摆设，也不是万能筐。它表达的是通信层/协议层状态，不是业务逻辑状态。
正确姿势：
-
401只用于认证失败（无 token / token 格式错），403用于鉴权失败（token 有效但权限不足） - 业务错误如“库存不足”“订单已取消”，一律返回
200+ 自定义code字段，避免前端把400当网络错误重试 - 真正需要重试的场景（如临时性限流），才用
429；服务器崩溃必须是500，不能用200+"server_internal_error"掩盖
性能影响：滥用非 200 状态码会触发浏览器/网关默认重试逻辑，可能造成重复扣款等严重后果。
要不要给错误码加分类层级？
简单项目不需要。一上来就设计 "USER_001"、"ORDER_002" 这类带模块前缀的码，反而增加维护成本——模块拆分、合并、重命名时，错误码得跟着动，但调用方未必同步更新。
更务实的做法：
- 初期用扁平命名：
"insufficient_balance"、"order_not_found" - 当错误码数量超 50 个、且明显归属多个子域时，再按模块拆包，例如
user_errors.InsufficientBalance、order_errors.OrderNotFound - 永远不要在错误码里塞动态内容（如
"user_123_not_found"），这会让前端无法做静态判断，也破坏日志聚合分析
容易被忽略的一点：错误码的变更必须向后兼容。新加码可以，但已有码的含义绝不能变——哪怕它当初起名起错了，也得将错就错，另起新码替代。
