文档中心

云手机

回调接口

任务执行失败回调

任务执行失败回调

回调名称 CallBackTaskRunFailed，任务执行失败时会触发该回调。

注意

取消链路异常时，系统也会发送 Event="failed"。此时 LegacyErrCode 可能为 "CANCEL_EXECUTION_FAILED"，建议按失败事件，并结合错误码进行处理。

回调参数

参数	类型	示例值	描述
AccountId	String	111111****	火山账号 ID。
RunId	String	run-141***	运行 ID。
Event	String	failed	回调事件类型，取值： status：任务开始执行、任务成功完成、提交取消、取消完成时触发。 failed：任务执行异常时、取消链路本身出现异常时触发，即当触发任务执行失败回调时返回此参数。 interrupt：任务需要用户补充信息、登录、审批或人工介入时出触发。
Data	Dict	{"Status": 6, "ErrCode": 500, "ErrMsg": "执行失败"}	返回失败事件的数据集合，参见 Data 字段说明。

Data 字段说明

参数	类型	示例值	描述
Status	Integer	6	任务状态码，当前回调仅返回“6：任务已失败（failed）”状态码。
ErrCode	Integer	500	错误码，详情参见业务特定错误码。
LegacyErrCode	String	-	当前回调链路中返回的旧版错误码。在任务失败事件中，该字段可能为空或返回以下取值： TASK_EXECUTION_FAILED：普通任务执行失败时使用的 legacy 错误码。 CANCEL_EXECUTION_FAILED：取消任务过程中发生异常时使用的 legacy 错误码。
ErrMsg	String	执行失败	错误信息。
Error	Object	-	结构化错误详情，参见 Error 字段说明。
StepIndex	Integer	5	任务失败时，发生错误的步骤序号。
RetryCount	Integer	2	重试次数。
TotalSteps	Integer	12	任务的总执行步数。
DurationMs	Integer	12312	任务耗时，单位为毫秒（ms）。

Error 字段说明

参数	类型	是否必填	描述
Category	String	是	错误分类，取值： request：请求入参、请求流程或取消请求相关异常。 resource：云电脑、设备实例等资源不可用或不可达。 environment：目标应用或运行环境异常，例如未安装应用、启动失败等异常情况。 agent：Agent 自身执行流程异常，例如超时、步数耗尽等。 hitl：需要用户或人工介入后才能继续执行。 model：大模型调用、配额、内容安全等模型侧异常。 tool：工具或技能执行异常。 result：任务执行结束但未达成目标结果。 security：安全策略或风控规则触发导致的异常。 platform：平台侧未知错误，服务不可用或环境不兼容。
CategoryCode	Integer	是	错误分类码，取值： 1000：对应 Category = request 异常分类。 2000：对应 Category = resource 异常分类。 3000：对应 Category = environment 异常分类。 4000：对应 Category = agent 异常分类。 5000：对应 Category = hitl 异常分类。 6000：对应 Category = model 异常分类。 7000：对应 Category = tool 异常分类。 8000：对应 Category = result 异常分类。 9000：对应 Category = security 异常分类。 10000：对应 Category = platform 异常分类。
FailureType	String	是	失败性质，取值： deterministic：确定性失败，在相同输入和环境下通常会稳定复现，不建议盲目重试。 stochastic：随机性失败，受资源、网络或服务波动影响，重试可能会恢复。
Owner	String	是	异常事件的归责主体，取值： client：归因于调用方接入侧或请求发起侧。 user：归因于终端用户（通常指需要用户补充信息、确认或执行相关操作的场景）。 agent：归因于 Agent 的规划、推进或执行逻辑本身。 model：归因于底层大语言模型服务或模型输出。 platform：归因于平台的基础设施、底层依赖服务或系统基础能力。 governance：归因于安全治理或风控拦截策略。
Retryable	Boolean	是	是否建议重试。
Recoverable	Boolean	是	是否可恢复。
AgentAction	String	是	Agent 服务侧建议操作，取值： stop：立即终止当前任务，不继续重试。 retry：立即重试当前动作或任务。 retry_with_backoff：延迟一段时间后重试，适合资源波动或临时性失败的情况。 stop_and_request_user：先停止执行任务，并请求用户补充信息、审批或协助。 stop_and_request_login：先停止执行任务，并提示用户先完成登录后再继续。
UserAction	String	是	建议用户执行的操作说明。
DocSlug	String	是	错误说明文档标识，格式如 errors/4000003。
HitlPolicy	Object	条件返回	用于指明人工介入的具体操作策略，仅在当前任务需要人工介入时返回此字段。详情请见 Error.HitlPolicy 字段说明。
Details	Object	是	承载异常或事件的动态扩展信息。在序列化输出时，系统会自动将键名（Key）从蛇形命名法（snake_case）转换为大驼峰命名法（PascalCase）。详情请见 Error.Details 字段说明。

Error.HitlPolicy 字段说明

参数	类型	是否必填	描述
Required	Boolean	是	是否必须人工介入处理。
Mode	String	是	人工介入的模式，取值： none：无需人工介入。 request_login：需要用户先登录，完成后才能继续执行。 request_approve：需要用户审批、授权或确认后才能继续执行。 request_more_info：需要用户补充验证码、查询条件等额外信息后才能继续执行。 request_human_help：需要人工协助处理问题后才能继续执行，例如卡死、复杂障碍或流程外等问题。
Blocking	Boolean	是	是否阻塞当前任务的继续执行。
ResumeSupported	Boolean	是	是否支持从当前中断节点恢复执行。
TimeoutSeconds	Integer	是	等待人工介入的超时时间，单位为秒（s），默认值为 0。
SuggestedActor	String	是	人工介入建议的干预处理方，取值： end_user：建议由终端用户本人处理。 operator：建议由客服、运营或人工处理。
ResumeAction	String	是	恢复执行时的动作。当前固定取值为 resume，表示人工介入完成后，从当前中断点继续执行。

Error.Details 字段说明

参数	类型	返回条件	描述
Exception	String	模型/平台异常	引发异常的具体类名（例如 ArkRateLimitError）。
Budget	Integer	Token 预算超限	任务整体输出的 Token 预算上限。
OutTokens	Integer	Token 预算超限	当前累计输出的 Token 数量。
InTokens	Integer	Token 预算超限	当前累计输入的 Token 数量。
TotalTokens	Integer	Token 预算超限	当前累计消耗的总 Token 数量。
ToolName	String	工具执行失败	执行失败的工具名称。
ToolErrorCode	String	工具执行失败	工具侧返回的原始错误码。若该值非纯数字，顶层的 ErrCode 将统一回退为 7000001。
StepIndex	Integer	工具执行失败	发生执行失败时的步骤序号。
StatusCode	Integer	模型状态异常	模型服务返回的 HTTP 状态码。
ArkCode	String	模型状态异常	模型服务返回的具体错误码。
OriginalErrorCode	String	触发风控策略异常	被风控策略改写前的原始数字错误码。
OriginalCategory	String	触发风控策略异常	被风控策略改写前的原始错误分类。
OriginalOwner	String	触发风控策略异常	被风控策略改写前的原始归责主体。
ReflectionFailureType	String	触发风控策略异常	模型反思阶段给出的失败类型。
ReflectionDescription	String	触发风控策略异常	模型反思阶段给出的失败描述。
RiskDetectedBy	String	触发风控策略异常	风险的检测来源。当前固定取值为 model_reflection。
HitlMode	String	触发风控策略异常或任务执行被中断时返回的异常	补充记录的人工介入模式。

回调示例

最近更新时间：2026.09.30 11:04:50

这个页面对您有帮助吗？

有用

有用

无用

无用