Error Types
把稳定类型当成分支键，而不是把报错文案当成分支键
这一页讲的是错误分类本身：ProfileClaw 如何命名失败、这些类别该如何影响编排，以及如何让自动化始终对齐正式契约里的错误码。
`type` 是正式契约，`error` 只是辅助说明。
如果 runtime 按自然语言报错分支，它迟早会漂移；如果按 machine-readable type 分支，就能持续对齐 API 表面。
这页的用途
当你在设计机器行为、SDK 分支或重试策略输入时，优先看 Error Types。
分类法
理解 auth、validation、resource、rate-limit、server 等错误家族的命名方式。
- 把每个 type family 当成长期稳定的分支面。
- 不要靠人类可读 `error` 做字符串匹配。
- 让编排逻辑保持 typed 和显式。
恢复策略
决定哪些类别该重试，哪些该重配，哪些该立刻停止。
- rate-limit 和部分瞬时 server 失败可以重试。
- validation 失败要先改输入。
- auth 和 scope 失败应视为接入配置问题。
契约对齐
利用 OpenAPI `x-error-codes` 和 typed client 让 docs、工具与 runtime 保持一致。
- 上线前先枚举预期错误码。
- 用测试夹具覆盖关键分支。
- 把未文档化错误码当成契约漂移信号。
按类别建模错误处理，而不是按端点情绪建模
绝大多数失败都可以落回少数几类可复用家族。这样 runtime 只要先完成一次分类，就能把相同策略复用到多个端点。
- auth 和 scope 失败通常意味着要修正凭证或能力配置。
- validation 失败意味着必须先修改请求结构或输入。
- rate-limit 和瞬时 server 失败才是主要重试对象。
把 typed branching 和用户文案分开
强健的集成可以对用户展示清晰友好的文案，但底层自动化、调试和审计仍然基于原始 typed envelope。
- 在应用层把 `type` 映射成你自己的友好提示。
- 保留原始 envelope 用于排障和复盘。
- 不要训练模型去适配措辞变化。
类别对比
这张表说明主要错误家族在 runtime 里通常应该如何处理。
| 类别 | 典型含义 | 默认动作 |
|---|---|---|
| Auth / Scope | key 缺失、无效，或没有所需能力。 | 停止并重新配置凭证或 scopes。 |
| Validation / Resource | 请求结构有误、输入缺失，或目标资源不可用。 | 先修正输入或路由，再重新执行。 |
| Rate Limit / Server | 请求本身有效，但系统当前暂时无法服务。 | 使用有边界的退避重试，并保留观测性。 |
决策矩阵
当 runtime 收到 typed error 时，可以按下面的方式决定动作。
情况
收到 `rate_limit.exceeded`
动作
等待；如果有 `Retry-After` 就尊重它，然后做有边界的退避重试。
原因
这类请求未来可能在不改输入的前提下成功。
情况
收到 validation 类型错误
动作
停止循环，先修改请求结构或补齐字段。
原因
重复发送同一个非法请求只会制造噪音。
情况
收到 auth 或 forbidden 类型错误
动作
把它视为能力或 secret 配置错误。
原因
修复凭证的是 runtime，不是模型。
代表性 envelope
让 runtime 按这样的 typed envelope 分支。
{ "error": "Rate limit exceeded", "type": "rate_limit.exceeded"}{ "error": "Missing required field: targetRole", "type": "career_prediction.missing_target_role"}下一步
理解分类后，再继续查看运行时错误流和端点级错误码。