API 错误码设计规范 + 前后端协作踩坑清单（含 5 个真实踩坑案例拆解）

背景

我做了 3 年技术产品经理，带过前后端协作最多的坑就是错误码：后端随手写 code=500 兜底一切、前端写 if (code !== 0) toast("出错了") 然后用户永远不知道为什么失败。每个团队都重新踩一遍。

社区里目前没有一篇把「错误码该怎么设计、前后端怎么约定、哪些坑会炸」讲透的委托。我想把这个活外包给真正在一线写过 API 的人。

最终要什么

一篇 1500–3000 字的结构化文章（Markdown），包含以下四个部分：

1. 错误码分层设计规范：HTTP 状态码 / 业务错误码 / 子错误码三层怎么分工，给出命名规则、段位划分建议（如 40000–49999 为客户端错误、50000–59999 为服务端错误），附一个可直接复制的 JSON 响应体模板（含 code、message、detail、traceId、timestamp 字段）。
2. 前后端协作契约：错误码文档该谁维护、怎么同步（OpenAPI / 独立错误码表 / 代码生成）、前端怎么做统一拦截与降级展示，给出 2–3 种主流做法的取舍对比。
3. 5 个踩坑案例：每个案例 200–300 字，格式固定为「现象 → 根因 → 修复 → 预防规则」。必须覆盖以下 5 个场景（可替换其中 1 个为你亲历的其他场景，但需注明）：
   • 批量接口部分成功时错误码怎么表达
   • 第三方服务超时被前端当成业务错误
   • 错误码复用导致前端误判（如旧版 code=1001 是"未登录"，新版改成了"参数非法"）
   • 幂等重试时错误码丢失导致重复扣款 / 重复下单
   • 网关层和微服务层错误码不一致，前端拿到的是网关 502 但实际是下游 504
4. 避坑 Checklist：10–15 条可勾选的发布前检查项，按「后端 / 前端 / 联调」三列分组，每条一句话说明"为什么"。

输入与上下文

• 不绑定具体技术栈，但示例代码/JSON 优先用 Node.js (Express/Fastify) + React 或 Java (Spring Boot) + Vue，二选一，文中注明即可。
• 如果引用了社区里已有的文章（如分布式事务科普 id=2189），请在正文中用"参见"标注。
• 不需要跑通 demo，但要保证示例代码片段语法正确、可直接复制到项目里。

交付格式

• 单个 Markdown 文件，UTF-8，含一级标题 + 四个二级标题对应上面四部分
• 代码块标注语言（json、js、java 等）
• 文末附「参考 / 延伸阅读」列表（≥3 条，可以是社区内 post 或外部链接）
• 全文 1500–3000 字（中文字符数），不含代码块