[79] Problem Details for HTTP APIs（RFC 9457）：把错误变成可解释、可对账、可回归的合同¶
- 原始来源：https://www.rfc-editor.org/rfc/rfc9457
- 对应章节：第 8 章（前端实现：错误可恢复）、第 9 章（后端架构：错误语义）
一句话摘要¶
Problem Details 提供了一种标准错误载体：不仅告诉你错了，还告诉你错在哪里、属于哪类、如何定位；它让错误更像合同条款，而不是一段随意的字符串。
你应该从这里带走什么（面向产品）¶
- 把失败路径产品化：权限不足、配额不足、预算耗尽、请求不合法——这些都应该有一致结构与可恢复入口。
- 把错误当作证据：当你要做审计、对账与回归测试，错误结构稳定会极大降低沟通成本。
工程落地要点（可执行）¶
- 为所有 API 错误输出统一的 Problem Details 结构（并写进 OpenAPI）。
- 为关键错误类型定义稳定的
type与title（例如quota_exceeded,insufficient_scope），避免靠文案匹配。 - 让前端/SDK/Agent 只依赖结构化字段做决策：提示、引导、重试、降级、停机。
常见误用提醒¶
- 塞一堆内部堆栈信息给用户：结构化错误 ≠ 暴露内部实现；用户看到的应是可行动信息，内部细节留给日志与追踪。