# 错误与重试

Version: a2bc6a0f021ec643

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

| 状态 / 类型 | 建议处理 |
| --- | --- |
| 400 / VALIDATION_ERROR | 读取 error.details 的字段路径，重新查看实时 inputSchema，修正参数；不要原样重试。 |
| 401 / UNAUTHORIZED | 凭证可能过期、撤销或飞书身份失效。有有效 refresh_token 则尝试续期一次，否则重新发起飞书登录。 |
| 403 / FORBIDDEN | 区分 business_scope 不足和业务角色/数据权限不足。scope 不足需按任务重新登录申请；业务权限不足应停止并告知用户，换 token 不会获得管理员权限。 |
| 404 / NOT_FOUND | 可能是不存在、不可见的记录或未开放接口。不要猜 ID 或改用管理接口绕过。 |
| 409 / 冲突 | 版本、重复候选人、幂等键或岗位影响预览可能冲突。先读最新数据和错误码再决策，不要覆盖他人更新。 |
| 429 / 限流 | 遵守 Retry-After（如果提供）；否则指数退避，限制重试次数，不要并发撞接口。 |
| 5xx / 暂时不可用 | 读取可有限退避重试；写入仅以相同 requestId 和相同内容重试。不要把服务异常当作登录失效。 |

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