跳转到主要内容
先确定错误发生在 HTTP 请求、后台 Run、Tool 调用,还是本地命令。请求被接受后,Run 仍可能失败或等待;HTTP 成功不能证明云任务成功。下表是常见错误的处理索引,不是全部内部错误字符串的公开稳定承诺。

HTTP 与 SDK 错误格式

这是说明格式的示例,不是执行日志。HTTP handler将 Zod 校验失败转换为 400 invalid_request 和字段路径;ExecutionError 返回自己的状态码及 error.code。Fastify 的客户端请求错误变为对应 4xx 的 invalid_http_request,例如请求体过大;未分类异常返回 500 internal_error,不泄露数据库查询或上游异常。 缺失或无效身份返回 401 unauthorized。不能通过重试修复权限;核对部署 URL、Token 和角色。租户范围查不到的资源可返回 404,不透露它是否属于其他租户。 Python 与 TypeScript 的 HexagonError 均提供 status、code,普通请求在响应缺少结构化码时使用 http_error。SDK 不保留上述 fields 数组为异常属性。网络断开、超时、JSON 解析或本地发现错误不保证包装成 HexagonError;TypeScript 流打开失败使用 event_stream_failed,Python 流截断可能抛 ConnectionError。不要把所有异常都当作服务端已拒绝请求。实现见 Python、TypeScript。

按阶段处理

“HTTP”列记录对应 ExecutionError 分支的状态;后台 worker 路径也可能把该错误记录到 Run 或事件中,而不是直接作为当前客户端响应。源码链接标识真实分支,不能据此推断该分支本轮已测试通过。

成功响应中也可能包含失败结果

HTTP 成功不一定表示操作成功。连接验证会捕获远程验证失败,返回 status: invalid、限定范围的 validation.code 和 enabled: false,不一定触发 SDK 异常。启用前重新检查 status。connection_changed_during_validation 则表示验证期间配置变化或被删除,原版本已无法更新;远程验证请求可能已经发生。 同样,Tool 对账返回 state: completed 表示结果已持久交付。调用方核实的 outcome: failed 会使交付的 Tool 结果包含错误,不代表外部写入成功。重复已记录的相同 resolution 会返回原记录,不兼容的替代证据产生 tool_resolution_conflict。应检查 resolution 内容,不只看外层 state。

预检原因不是另一套重试指令

组合预检返回 compatibility.reasons,包括 incompatible_model、harness_tools_unsupported、sandbox_oci_image_unsupported、sandbox_private_image_unsupported、harness_initialization_unsupported、missing_capability、network_policy_unsupported、credential_proxy_not_allowed_by_network_policy。它们是能力不匹配原因,不应一律解释成相同 HTTP 响应或远程分配失败。修正组合或明确调整用户要求;不能把 allowlist 静默改为 unrestricted。

重试之前确认原操作

  • 查询或事件流的传输故障:有界退避,重连同一 Run 与已提交游标,认证错误先修正身份。
  • Run 提交响应丢失:用同一 Session、input、origin、幂等键恢复原提交,不生成新键。
  • Session 或云资源创建响应丢失:保留意图、原 ID 和时间,查询原对象及操作,不假设有 Run 提交同样的幂等契约。
  • Tool 写入结果未知:检查调用、request hash 和固定执行策略,核实上游结果后 resolve,不重发写入。
  • 关闭或删除未确认:保留资源与删除回执,对账原操作;停止服务或没有列表结果并不普遍证明清理完成。
资源可能已存在、写入可能已生效。internal_error 或客户端超时都不能保证“没有发生任何事情”。参考恢复与对账。

三种恢复判断

服务端已接受提交,但客户端超时。 在持久请求记录中保留原 Session ID、完整 input、origin 和幂等键,再提交完全相同的意图。哈希匹配时服务端返回原 Run;在相同 key 下修改文本或 origin 会产生 idempotency_conflict。新 key 代表另一次提交,可能重复执行。见持久后端示例。 用户在取消之后点击批准。 过时决定可能返回 stale_approval,应读取原审批和 Run,不创建新审批绕过响应。重复已记录的相同决定可以返回该记录,但仍不能证明外部操作已经执行;Tool 结果及取消竞态结果需要单独核查。 模型产生输出,但导出失败。 即使 Harness 进程已经运行,worker 也可能以 artifact_export_rejected 将 Run 结束为 failed。查询已持久化产物、原 Run 与事件。重新执行整个任务可能重复文件修改或外部副作用;先诊断导出失败,再判断是否需要下一轮。该 worker 错误记录在 Run 上,不是此前成功 submit 请求的 HTTP 状态。

记录错误时保留原本含义

应用错误记录应包括操作种类、请求关联 ID、异常类别、可取得的 HTTP 状态和 code,以及是否已经知道 Run ID。恢复所需的完整输入、key 和资源引用放在私有持久状态中,不写入公开日志。只凭 SDK 异常文本不足以选择重试策略。 写操作丢失响应时,应单独记录“提交结果未知”,不能因为客户端抛异常就标记为“已拒绝”。只读事件观察可以重连同一 Run;创建资源或外部写入需要先查询原操作。一个通用 HTTP 409/500 处理器不能为这些情况安全地选择相同动作。

未分类错误与本地命令

记录发生时间、请求方法和去除秘密的路径、HTTP 状态、结构化码、应用关联 ID,以及私有 Session/Run/操作标识。查询持久 Run、Tool call 和资源操作状态,再导出诊断。不要记录 Authorization、带访问授权的预览 URL、原始凭据或完整用户输入。 本地启动器、依赖探测、Provider SDK 和部分 Runtime 错误仍可能是文本或普通异常,没有统一 HTTP 码。按 CLI及对应集成页处理,不能为它们臆造 API code。源码或证据仍不明确时保留未知状态,并报告已观察事实与未验证部分。 常见错误表的全部 41 行均已匹配所链接源码中的实际 code/status 分支,见分支核对记录。这验证本页索引,不代表穷举每个内部错误字符串或运行路径,也不声称新执行了远程故障注入。下一步:按症状排查、限制、恢复。