切换主题
错误与重试策略
接口错误返回统一结构，任务开始后的失败通过事件和 Run 终态呈现。程序判断 status/code，不依赖人类可读 message 的固定文本。
json
{"error":{"code":"REVISION_CONFLICT","message":"配置修订不匹配","traceId":"trace_example","retryable":false,"details":{}}}此处错误文本为结构示例，具体 code 以实际响应为准。
HTTP 状态处理
| HTTP | 原因 | 推荐动作 |
|---|---|---|
| 400 | 参数、协议、Schema 不合法 | 修改请求，避免无效重复 |
| 401 | 身份无效、过期、撤销 | 从可信身份层重新取得凭据 |
| 403 | 角色或应用作用域不允许 | 检查权限配置，不切换成他人身份 |
| 404 | 资源不存在或对当前身份不可见 | 核对精确标识和所有者 |
| 409 | 版本、依赖、幂等、会话或操作冲突 | 读取当前状态后解决冲突 |
| 410 | 游标无效或事件过期 | 读取任务摘要，需要时由管理员导出归档 |
| 412 | If-Match 修订冲突 | 重新读取并合并改动 |
| 413 | 请求过大 | 缩减正文或按知识导入限制拆分 |
| 429 | 并发或预算限制 | 检查当前负载与预算，不快速循环重试 |
| 502 | 上游服务失败 | 结合 traceId 核查模型/业务响应 |
| 503 | 能力租约或密钥等不可用 | 恢复配置和服务健康后再发请求 |
| 500 | 服务内部错误 | 保留脱敏诊断信息并检查日志 |
哪些操作可以恢复
- 事件读取：使用既有 runId 和 Last-Event-ID 重连。
- 配置读取：在网络恢复后重新读取。
- 聊天受理：只有同一次业务请求才能使用原幂等键与原正文恢复。
- 危险操作批准：读取确认与任务状态，不修改参数或反转已保存决策。
- 写工具：先核查 callId 的实际业务结果，不能根据网络超时直接再次执行业务。
任务失败与用户反馈
FAILED、TIMED_OUT、CANCELLED 都是终态。WORKER_LOST 或 PROCESS_RESTARTED 表示执行被明确终结，不能用“正在自动恢复”误导用户。用自然语言说明任务未完成，并提供可核查的运行编号。
配额拦截
QUOTA_EXCEEDED / QUOTA_PRICE_UNKNOWN / QUOTA_TOKEN_BOUND_UNKNOWN / QUOTA_CURRENCY_MISMATCH 均在发送边界拒绝额度分配，不能隐式切换或自动重试。详见应用配额与费用预算。