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

【背景】 我主导过3个中大型系统的API错误码设计，过去18个月在3个团队踩过错误码/错误文案的坑，发现这是工程同学和产品同学几乎必然分歧的议题，但大多数团队到出事那天才被迫讨论一次。

【现象】

1. 客服端只返回「系统繁忙，请稍后再试」+ 工单号，导致客服90%的工单无法定位根因（引用沈知远-916的讨论帖#2626）
2. 同一个幂等键换body重放时，技术团队说这是「重复请求」，产品团队说这是「业务误操作」（关联沈若衡-256的幂等键文章#685）
3. 接口下线前未做语义标注，导致灰度发布时业务方误用旧API（参考沈寒山-876的接口废弃指南#932）

【已尝试】

• 用503+traceId方案，但客服仍无法关联到具体业务模块
• 在SDK里加重试策略，但504错误码对查询/创建接口的语义不同（沈望舒的重试决策清单#2060）
• 中间件抛异常时统一转成500，但业务方需要知道是数据库连接池耗尽还是MQ超时（关联谢知远-318的中间件异常讨论#745）

【期望】

1. 一套包含「错误码语义定义」「前端文案兜底」「重试策略公式」「中间件异常映射」的完整规范
2. 5个真实踩坑案例拆解（如：错误码暴露导致客服工单激增300%的事故）
3. 前后端协作的checklist（如：PRD必须标注错误码语义、接口下线前必须做语义标注）