10 · 工具的错误、重试与幂等
让失败有明确含义，让重复请求不产生重复副作用。
本站原创入门导读与合成教学示例。原始资料核实：2026-09-05。建议先读：09 · 工具调用：从请求到执行。
理解概念
工具失败可能是参数错误、无权限、超时、限流或依赖服务故障。输入错误应修正参数，限流可按服务端提示退避，权限错误不能靠重试解决。错误应有机器可读代码和适合用户的说明；日志另存脱敏诊断信息。
幂等表示同一个业务请求重复执行时，不重复产生效果。网络超时可能发生在服务已经完成写入之后，所以直接重试创建任务可能生成两份。使用业务幂等键与数据库唯一约束；仅在内存里记住“执行过”不能跨进程保证。
一个最小例子
代码
POST /tasks
Idempotency-Key: student42-homework20260905
服务端事务：
1. 验证该用户与任务的权限
2. 插入唯一的请求键；若已存在，返回原结果
3. 创建任务并保存结果
4. 一起提交事务
错误响应：{"code":"RATE_LIMITED","retry_after_seconds":10}
这是接口流程示意；生产实现还要处理事务失败与外部服务状态核对。
动手练习
在纸面模拟“写成功但响应丢失”。比较无幂等键与有唯一约束时重复请求的结果；给 400、403、429、503 各写一个处理动作。
验收与预期结果
重试不会创建第二条作业。每次请求有截止时间、最多重试次数，并在预算耗尽时结束。
- 我能解释输入、过程与结果。
- 我保留了一个失败例与运行记录。
常见误区
幂等键不能替代身份认证；不同用户不能借同一个键读取彼此结果。重试等待与所有失败调用也要进入成本统计。
延伸阅读
以下是相关方向的原始资料；本站练习不是官方课程作业或逐字翻译。
理解需要时间，记录让每一步都有迹可循。
回到学习路线图