SDK 错误处理 Hook

按错误发生位置决定提示、重试或终止，并保留可诊断信息。

This page has not been translated into English yet. The original Chinese version is shown below.

onErrorOccurred 在会话执行出现错误时调用。可用它记录问题、展示适合用户的说明或选择恢复方式；工具失败后的模型提示则另有 onPostToolUseFailure。

错误输入

字段	含义
`error`	错误字符串
`errorContext`	model_call、tool_execution、system 或 user_input
`recoverable`	是否可能恢复
`cwd`	当前工作目录
`timestamp`	专门参考表定义的 number / Unix timestamp

invocation.sessionId 用于关联会话。recoverable 表示有恢复可能，不是保证重试成功；应用仍需区分临时模型问题、工具参数问题和无法继续的系统错误。

选择返回行为

输出字段	用途
`errorHandling`	retry、skip 或 abort
`retryCount`	选择 retry 时的重试次数
`userNotification`	展示给用户的自定义说明
`suppressOutput`	不向用户显示错误输出

返回 null 或 undefined 使用默认错误处理。隐藏显示不代表错误已修复；只应对已理解的非关键错误使用，并保留必要诊断记录。

针对可恢复模型错误重试

const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input, invocation) => {
      console.error("Session error", invocation.sessionId, input.errorContext);
      if (input.errorContext === "model_call" && input.recoverable) {
        return {
          errorHandling: "retry",
          retryCount: 3,
          userNotification: "A temporary model error occurred. Retrying.",
        };
      }
      return null;
    },
  },
});

3 次是本例应用策略，不是 SDK 默认值。该页没有说明统一退避间隔，也没有承诺任意副作用工具可安全重放，因此不把此示例改成所有错误统一重试。出现不可恢复错误时，应让应用保留明确失败状态。

不混用参考中未列出的字段

官方末尾建议提到 errorType 和 additionalContext，但本页输入表实际字段为 errorContext，输出表没有 additionalContext。这里按字段参考编写，不提供未经确认的错误 Hook 字段。

需要在失败工具后给模型下一步建议时，可返回onPostToolUseFailure已明确支持的 additionalContext。给用户看的 userNotification 与给模型的恢复上下文是不同目标。

记录、归类与清理

按 errorContext 和会话关联信息分类，能区分模型连接问题与工具执行问题。日志不必保存完整 prompt、工具参数或凭据；若确需详细数据，先按应用规则处理再写入。

错误处理应保持快速，慢的监控上报可以进入队列。按会话保存的最后工具或错误统计应在会话结束后清理，并考虑进程异常退出时结束 Hook 未运行的情况。