区分状态、类型和具体事件
RFC 9457 定义 application/problem+json。使用稳定的问题类型及针对本次事件的清楚说明；客户端不应解析翻译后的自然语言来决定动作。若含 status 成员，应与实际 HTTP 状态一致。
| 状态 | HTTP 含义 | 可考虑的处理 |
|---|---|---|
| 400 | 请求不正确 | 修正后再尝试。 |
| 401 | 缺少有效认证信息 | 检查凭据和约定机制。 |
| 403 | 已理解但拒绝请求 | 检查权限；重复不会获得权限。 |
| 503 | 服务暂时不可用 | 操作允许时，限定等待和重试。 |
让失败路径可预期
- 说明状态码、格式和预期处理，并测试空响应、网关的非 JSON 内容、连接中断和超时。
- 在服务端验证输入与权限。处理预期错误而不掩盖未知故障，不要将业务失败伪装为成功响应。
- 返回可供支持团队使用的关联标识，不在公开响应中包含堆栈、内部查询、密码或令牌。
只在合理时重试
5xx 并不许可无限重试。结合契约、操作状态、幂等性和总期限判断。报告缺陷时提供最小且脱敏的复现；修复后重测原场景及相邻的拒绝访问场景。
一手资料
API 错误应指导操作，避免信息泄露。
HTTP 状态提供初始类别，但客户端可能需要稳定的类型和有用的详细信息。RFC 9457 描述了常见的错误结构；它并不支持暴露内部跟踪或敏感数据。
- 区分永久拒绝、可纠正的输入和临时故障。
- 记录每个重要错误的类型、状态和客户端可能采取的操作。
- 测试响应是否不包含密钥或不必要的完整有效负载。
一手资料：IETF RFC 9457 — Problem Details for HTTP APIs. 相关方法：阅读实用指南.
API重试：计算端到端时间预算
规定调用上限和全局期限。
虚构教学案例：数字不代表CIE或客户实绩。
虚构模型：四次调用各上限250毫秒，等待100、200、400；不含抖动、连接、队列和本地验证。
- 总尝试次数
- 41 + 3
- 累计等待（ms）
- 700100 + 200 + 400
- 模型预算（ms）
- 17004 × 250 + 700
| 步骤 | 调用上限（ms） | 下次等待（ms） |
|---|---|---|
| 尝试1 | 250 | 100 |
| 尝试2 | 250 | 200 |
| 尝试3 | 250 | 400 |
| 尝试4 | 250 | 0 |
| 总计 | 1000 | 700 |
- 调用时间1,000
- 累计等待700
- 全局期限（ms）1,500
得出结论前的检查
- 1000 + 700 = 1700超过1500毫秒期限。
- 传递全局期限，防止重复效果；超时不证明远端取消处理。
试算重试预算
n × T + W × (2^(n−1) − 1)
相关方法：阅读实用指南.
API错误：类型、状态与证据
此语言版本的详细参考说明以英语提供。
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5