Python接口错误码需语义明确、层级分明、可扩展、不重复，推荐三位或四位分段编码（如2001表示用户模块参数错误），首位数字标识大类（1系统/2用户/3数据/4参数/5服务端/6第三方），后位标识具体场景；须用Enum定义并继承统一异常基类，配合HTTP状态码协同使用（如400+4001），禁止魔数硬写或滥用200响应业务错误，且需文档化、版本化管理。
Python接口开发中，错误码不是随便编个数字就行，关键是要让前后端协作高效、排查问题快速、后期维护清晰。核心原则是：语义明确、层级分明、可扩展、不重复。
错误码结构设计：三位或四位分段式编码
推荐采用 三位十进制数（如 100、401、503）或 四位分段编码（如 2001 表示「用户模块-参数错误」），兼顾HTTP状态码习惯与业务可读性。
- 首位数字表示错误大类：1=通用/系统级，2=用户/权限类，3=数据类（查不到、冲突），4=参数/客户端错误，5=服务端异常，6=第三方调用失败
-
后两位（或后三位）标识具体场景：例如
401是标准未授权，但业务中可定义2001（用户不存在）、2002（密码错误）、2003（账号被禁用） - 避免使用纯顺序编号（如 1001、1002…），否则无法一眼识别归属模块；也别直接复用HTTP状态码做全部业务码（比如用
404表示“订单不存在”可以，但不能用404表示“库存不足”）
统一异常基类 + 枚举管理错误码
不靠字符串拼接或魔法数字硬写，而是用 Python 枚举（Enum）定义所有错误码，并继承一个自定义异常基类，确保抛出、捕获、序列化行为一致。
- 定义
ErrorCode枚举，每个成员包含code（数字）、message（中文提示）、http_status（对应HTTP状态，如400/401/500） - 实现
APIException基类，接收枚举实例初始化，自动携带 code/message/status - 全局异常处理器（如 FastAPI 的
@app.exception_handler(APIException)或 Flask 的errorhandler）统一返回 JSON 格式：{"code": 2001, "message": "用户不存在", "data": null}
错误码与 HTTP 状态码协同，不强行一一映射
HTTP 状态码表达的是通信/协议层语义（如 400=请求无效，500=服务炸了），而业务错误码表达的是领域逻辑结果（如“优惠券已用完”“实名认证未通过”）。二者应配合，而非替代。
立即学习“Python免费学习笔记（深入）”；
- 参数校验失败 → HTTP 400 + 业务码
4001 - 未登录/Token过期 → HTTP 401 + 业务码
2004 - 数据库唯一约束冲突 → HTTP 409 + 业务码
3002 - 下游服务超时 → HTTP 503 + 业务码
6003 - 绝不用 200 响应体里塞一个
"code": 500—— 这会绕过前端的网络错误拦截逻辑
配套文档与演进管理：错误码不是写完就扔
错误码是接口契约的一部分，必须和 OpenAPI 文档、SDK、前端常量表同步更新。
- 用
pydantic模型定义标准响应结构，把code字段类型设为Literal或关联枚举，支持 IDE 提示和校验 - 在 Swagger / Redoc 文档中标注每个接口可能返回的错误码及含义（可用
x-code-samples或自定义字段） - 新增错误码必须走 CR（Code Review），禁止私下添加；废弃错误码保留历史记录，标记
deprecated，至少保留一个大版本 - 建议生成一份可搜索的
error_codes.md，按模块/场景分类，附 HTTP 状态、典型触发条件、建议前端处理方式
不复杂但容易忽略：错误码的价值不在定义那一刻，而在每一次被准确抛出、被前端友好展示、被日志精准归因、被新同学快速看懂。从第一个接口开始就定好规范，后面省下的调试时间远超初期多写的那几十行代码。
