API 开发 / 第 05 课
处理错误、用量与重试
区分输入错误、临时故障与输出未完成。
配合前面示例，先使用模拟响应测试。不记录 API 密钥或完整用户文档。重试可能增加用量，重复写工具也可能造成重复操作。
1. 按状态分类
400 检查请求和支出限制信息；401 检查密钥；403 检查资源和工作区权限；404 检查路径或模型；429 检查限流、支出上限与 retry-after；500／529 等临时故障可考虑有限重试。Worker 示例将上游错误包装为 502，并提供 upstream_status。
2. 有依据地重试
临时失败可尊重 retry-after，使用有上限的指数退避和随机抖动。支出封顶的 429 可能没有 retry-after，不应无限循环。参数错误、密钥撤销或无权限需要修正。下载的原生 fetch 示例明确报错，不自动重试；官方 SDK 自带重试策略，需配置而非叠加。
3. 保留诊断信息并识别截断
记录状态、安全的错误类别、request-id、耗时及 usage。200 也不一定成功，仍要检查 stop_reason 与工具错误。max_tokens 是输出未完成；流式响应发送 HTTP 头后仍可能失败，正式流客户端应处理流内错误事件。
4. 限定工作量
使用较小输出预算、限制工具轮数、校验输入大小，并区分读写工具。在 Console 设置支出限制并观察实际用量。工具定义和返回也消耗 token，一个工具循环可能包含多次模型请求，不能宣传为免费无限调用。
练习与自检
YOUR TURN / 动手练习
模拟 401、带 retry-after 的 429、max_tokens 和工具失败，说明何时修正、重试或向用户明确报错。
完成后，花一点时间检查：
阅读官方原始资料
CLI 操作已对照官方文档核查；API 示例通过模拟响应测试。未登录产品账户进行完整实机演示。