一项能力能否长期维护，不取决于演示是否成功，而取决于团队能否解释每个状态、每次重试和每一份残留数据。 HTTP 状态表达通用语义，应用 code 表达稳定业务原因。message 不作为程序分支，因为它会本地化、修改且可能包含不安全细节。
API 契约不仅是字段类型，还包括单位、缺省语义、幂等性、错误分类和版本窗口。客户端必须能区分可重试、需用户操作与永久拒绝，避免统一重试制造副作用。
设计时必须回答的问题
这项能力横跨客户端、网络与服务端，局部最优很容易制造全局故障。工程决策需要同时约束两端行为、持久化事实和运维预算。
- 响应含 code、safeMessage、requestId 和可选 retryAfter/details 字段；code 文档说明可重试性、用户动作与指标分类，未知 code 安全回退。
- 把协议事实、用户意图和自动恢复分层；自动化只能恢复事实，不能推翻用户明确选择。
- 兼容性通过显式能力协商决定，旧客户端得到可解释的降级路径，而不是进入半可用状态。
“API 错误码体系：让用户、客户端和运维看到同一个原因”的交付标准是正常路径可用、异常路径收敛、资源有界，并且用户能理解系统为何采用当前状态。 这样得到的不是演示代码，而是能解释、能降级、能回滚的生产能力。
边界情况不是附加项
生产问题往往发生在两个正确动作同时到达时。需要逐条检查迟到消息、重复执行、资源耗尽和版本交叉，而不是只补当前堆栈显示的那一行。
- 所有错误都返回 200 会破坏代理和监控；直接透出数据库或 TURN 原始文本会泄露内部信息并让客户端依赖供应商措辞。
- 失败被压成一个布尔值，调用方无法区分可重试、需用户介入与永久拒绝，最终形成无限循环。
- 降级路径从未压测，主路径故障时所有流量同时进入更慢、更昂贵的后备方案。
用证据确认它真的可用
用已知输入和可控故障建立金样本，然后把线上低基数指标与测试结果对齐。只有指标能提前识别同类退化，验证才真正延伸到生产。
- 对每个公开 endpoint 生成校验、未授权、冲突、限流和内部故障，契约测试核对状态、code、敏感字段与前端动作。
- 连续执行一百次开始、失败、重试和取消，检查句柄、监听器、队列及临时数据回到基线。
- 用故障注入验证告警先于用户投诉触发，并确认值班人员能从有限证据定位到具体阶段。
可以上线的标准是：用户知道当前发生了什么，系统在异常后能停止或恢复，资源不会无界增长，运维也能从最小必要证据定位阶段。