---

title: HTTP Problem Details(RFC 7807)：错误响应与契约治理

keywords:

• RFC 7807
• Problem Details
• 错误响应
• 契约
• 可观测

description: 采用 RFC 7807 标准化错误响应结构，统一字段与扩展，提升接口可诊断性与跨团队契约一致性。

categories:

• 文章资讯
• 技术教程

---

HTTP Problem Details(RFC 7807)：错误响应与契约治理

概览

• 使用 application/problem+json 提供结构化错误：type/title/status/detail/instance，便于客户端与可观测系统解析。
• 在网关与服务层统一错误契约与扩展字段。

技术参数（已验证）

• 媒体类型：application/problem+json 或 +xml；响应包含标准字段与扩展键。
• 字段：type（URI 或文档链接）、title（简要）、status（HTTP 状态码）、detail（人类可读）、instance（请求唯一标识）。
• 扩展：加入 error_code、trace_id 等扩展键；遵循命名与兼容。
• 网关协同：在网关统一转换错误为 Problem；保持跨服务一致。
• 可观测：在日志/Trace 中记录 instance/trace_id；便于关联诊断。

实战清单

• 在契约中定义错误结构与扩展；在 SDK 统一解析。
• 为高价值错误提供文档链接与修复建议；保持版本与兼容。
• 将错误事件与分布纳入看板；持续优化。