错误处理
先判断网络与 HTTP 状态，再解析业务响应。普通业务错误使用 {code, msg, data}，部分提供稳定 errorCode，不要通过比较中英文 msg 驱动逻辑。
json
{
"code": 409,
"msg": "Settings changed; reload before saving",
"data": null,
"errorCode": "SETTINGS_CONFLICT"
}示例只说明结构，不要求服务端返回完全相同的文案。
状态与处理方式
| HTTP 状态 | 客户端处理 |
|---|---|
| 400 | 根据 errorCode 和字段约束修正请求，避免原样重复提交 |
| 401 | 按认证流程刷新或重新登录；禁用账号、租户或撤销会话需先解除原因 |
| 403 | 检查当前身份、角色和操作权限，不自动无限重试 |
| 404 | 检查路径、代理前缀、资源和目标版本；生产文档入口默认关闭 |
| 409 | 重新读取并处理冲突；设置需要使用新的 revision |
| 413 | 检查文件、整个请求体及代理上限；返回可能是 HTML |
| 422 | 展示字段校验问题，检查类型、必填项与取值范围 |
| 429 | 遵守 Retry-After；不要立即循环重试 |
| 500 | 保留脱敏上下文并检查服务日志，写请求重试前确认上次结果 |
| 503 | 检查依赖、运行开关和服务状态；恢复后再重试 |
代理产生的 502 / 504、断网、超时或非 JSON 内容不一定有 errorCode。AI SSE 的业务结果在事件中，不能只凭 HTTP 200 判定成功。
字段校验与重试
请求校验失败通常为 422，字段信息位于 data.fieldErrors，每项包含 field 和 message。errorCode 是可选字段，客户端应能处理没有它的校验错误。
GET 等读取可按场景进行有上限的重试。创建、付款等业务写入是否可重试由该接口的幂等约定决定；HoHu 不自动使所有 POST 幂等。租户创建和初始化的 Idempotency-Key 规则见多租户管理。
开发与反馈
新增业务错误使用 app/core/exceptions.py 中的领域异常，分配稳定且明确的错误码，同步客户端翻译与回归验证。业务代码不直接散布 HTTPException，不向用户暴露堆栈、密钥或数据库连接。
反馈包含版本、操作步骤、发生时间、HTTP 状态、errorCode 和脱敏日志。先按常见错误码定位；此速查表不是完整错误注册表。