# 错误与重试

Version: 829db5245701f2f8

业务错误格式为 {error:{code,message,details?}}；飞书登录/续期协议错误格式为 {error:"...",error_description:"..."}。两者不要混淆。

| 状态 / 类型 | 建议处理 |
| --- | --- |
| 409 / RESUME_ATTACHMENT_REQUIRED | 候选人缺少可读取的简历原件。先在候选人详情补传类型为 resume 的真实简历附件，或请有附件编辑权限的同事补传，再重试；刷新、重登或换权限不能绕过。正文、联系方式、链接、screenshot/other 和孤立的 PDF 预览不算。 |
| 400 / VALIDATION_ERROR | 读取 error.details 的字段路径，重新查看实时 inputSchema，修正参数；不要原样重试。 |
| 401 / UNAUTHORIZED | 凭证可能过期、撤销或飞书身份失效。有有效 refresh_token 则尝试续期一次，否则重新发起飞书登录。 |
| 403 / FORBIDDEN | 先读 error.reason。agent_scope_missing 表示此连接缺少授权，requiredScopes 列出缺项：按本次任务汇总完整权限集合，重新 POST /api/v1/agent-auth/device 并让用户完成飞书验证；不要只申请缺项而漏掉仍需的读取/写入权限，refresh 不扩权。business_permission 表示用户业务权限不足，应停止并说明，换 token 不会获得权限。agent_endpoint_unsupported 表示用错接口，应改用 /tools，不要反复授权。 |
| 404 / NOT_FOUND | 可能是不存在、不可见的记录或未开放接口。不要猜 ID 或改用管理接口绕过。 |
| 409 / 冲突 | 版本、重复候选人、幂等键或岗位影响预览可能冲突。先读最新数据和错误码再决策，不要覆盖他人更新。 |
| 429 / 限流 | 遵守 Retry-After（如果提供）；否则指数退避，限制重试次数，不要并发撞接口。 |
| 5xx / 暂时不可用 | 读取可有限退避重试；写入仅以相同 requestId 和相同内容重试。不要把服务异常当作登录失效。 |

超时并不等于未写入。没有确认结果时保留原 requestId，以同样请求重试；不要生成新键重复添加备注、流程或事件。若最终无法恢复，报告具体接口、操作、状态码/错误码和发生时间，不记录 token 或完整隐私文本。