API Errors
理解完整失败流程，而不只是记住一个错误名字
这一页解释的是运行时错误处理：响应 envelope、重要 headers、重试姿态，以及它和更窄的 Error Types 分类页之间的区别。
Format: AI-first docs
Source: DocsApiErrorsPage
信息
`/docs/api/errors` 是运行手册；`/docs/api/error-types` 是分类参考。
当你在实现 runtime 行为或排查真实故障时看这页；当你想理解稳定命名体系时看 Error Types。
这页覆盖什么
API Errors 关注的是一次失败请求在生产环境里应该怎样被完整处理。
Envelope 处理
读取归一化 JSON body，并判断到底发生了哪种失败。
- 先看 `type`，再看 `error`，最后看可选 details。
- 把原始 envelope 保留给日志和支持工具。
- 把 body 当成 runtime 输入，而不只是 UI 文案。
Header 语义
限流和版本 headers 会直接影响 runtime 的下一步动作。
- 通过 `Retry-After` 做退避感知重试。
- 记录 `X-RateLimit-*` 做节流与观测。
- 在调试和支持流程里使用 `X-API-Version`。
调试流程
从失败采集进入分类，再进入安全的下一步动作。
- 把接入失败和请求结构失败分开。
- 把重试逻辑留在 runtime adapter 内部。
- 对未知故障保留足够元信息，方便后续追查。
把 envelope 和 headers 一起读
好的 runtime 不会只看 JSON body。状态码、限流 headers 和重试元信息，通常和 typed error 字段一样重要。
- 结合 status 和 `type` 一起完成分支判断。
- 使用 `Retry-After` 与 rate-limit headers 决定节奏。
- 记录请求身份和 headers，但不要泄露 secrets。
把运行时处理和分类设计分开
Error Types 解释失败如何命名；API Errors 解释线上系统在失败真的发生时该怎么响应。
- 这一页用于设计 runtime 行为和故障响应。
- Error Types 用于在代码和 SDK 里建立稳定分支键。
- 在内部文档里同时链接两页，避免构建者混用。
Errors 与 Error Types 的分工
这两个文档应该服务不同任务，而不是彼此重复。
| 表面 | 主要回答的问题 | 适用时机 |
|---|---|---|
| API Errors | 当前这次失败请求，runtime 现在应该怎么处理？ | 实现、调试、重试、运维手册阶段。 |
| Error Types | 契约用什么稳定类别和名字来命名失败？ | 设计 typed branching、SDK 和契约测试时。 |
| OpenAPI x-error-codes | 这个具体操作可能出现哪些错误码？ | 生成客户端、测试夹具和端点级预期时。 |
决策矩阵
当线上请求失败时，可以按下面的流程决定下一步动作。
情况
响应里带有 `Retry-After` 或 rate-limit headers
动作
在 runtime 里退避，并安排一次有边界的重试。
原因
服务端已经明确告诉你什么时候再尝试更安全。
情况
请求以 validation 或 missing-field 类型失败
动作
先停止并修正 payload 或路由选择。
原因
传输层重试无法修复一个结构错误的请求。
情况
runtime 遇到未知失败模式
动作
保留原始 envelope、headers、request id，并升级排查。
原因
未知失败应沉淀成可观测的契约或实现问题，而不是静默循环。
代表性失败 payload
这些示例说明 runtime 在失败时到底该检查什么。
限流感知失败
1
{2
"error": "Rate limit exceeded",3
"type": "rate_limit.exceeded"4
}校验失败
1
{2
"error": "Missing required field: targetRole",3
"type": "career_prediction.missing_target_role"4
}下一步
理解运行时处理之后，再继续看稳定分类和端点级错误码。