> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 错误处理
> 了解工作流调用错误，控制步骤失败行为，并使用工作流日志和追踪调试失败的运行
# 错误处理
当工作流请求失败、步骤行为异常或回调投递未按预期完成时，请使用工作流错误处理文档。目标是将请求验证问题与工作流运行时失败区分开来，让你知道接下来该去哪里查找。
## 概述
工作流失败发生在两个不同的层级。第一层是公共 invoke 路由上的请求验证。第二层是运行启动后的工作流执行。
对于执行失败，最有用的调试界面是 [日志](./logs)，你可以在那里查看运行详情面板、追踪瀑布图、输出和回调投递尝试。
## 如何处理工作流调用请求错误？
从 `POST /v1/workflow/invoke` 的响应体开始。
当必填的调用字段缺失或无效时，当前的公共路由会明确返回验证错误。
示例：
```json theme={null}
{
"error": "Missing required field: deployment or variant"
}
```
```json theme={null}
{
"error": "callback_url is required when async is enabled"
}
```
```json theme={null}
{
"error": "callback_url must be a valid URL"
}
```
请先修复这些请求层面的问题，再去检查工作流本身。
## 如何控制工作流步骤失败时发生的行为？
在编辑器中打开工作流。
点击某个步骤以打开 **Step settings**。
对于公开了该设置的步骤类型，使用 **When the step fails** 选择该步骤失败后工作流应停止还是继续。
当工作流应在该失败时立即停止时，使用 **Terminate Workflow**。
当失败的步骤不应阻止工作流的其余部分时，使用 **Continue**。
子工作流步骤遵循同样的规则。如果子工作流失败，子工作流步骤会被标记为失败。**Terminate Workflow** 会停止父工作流，而 **Continue** 会记录失败并让父工作流继续运行。
此设置会影响运行时行为，因此更改后请再次测试工作流。
## 如何调试失败的工作流运行？
打开 [日志](./logs)。
在表格中找到失败的运行，然后将其打开。
使用追踪瀑布图识别失败发生的位置。在运行中逐步查看所选 span 详情、请求详情、启动输入、元数据和输出部分。
如果工作流使用了回调投递，还可查看 **Webhook Logs** 以了解重试次数、响应代码、负载和响应体。
这是将步骤失败与投递问题区分开来的最佳方式。
{/* Add screenshot: failed workflow trace detail */}
## 我应该预期哪些运行时失败状态？
当前的公共工作流路由可以呈现终止失败状态，例如：
* `failed`
* `cancelled`
如果直接响应路由等待工作流完成的时间过长，它也可以返回超时失败。
例如：
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "failed",
"error": "Workflow timed out"
}
```
或：
```json theme={null}
{
"request_id": "req_019d52846ea37682b03522fd0695cc43",
"run_status": "cancelled",
"error": "Workflow run was cancelled"
}
```
将这些视为运行时失败，而不是请求格式问题。
## 错误处理说明
如果 invoke 请求成功但工作流随后失败，请先转到工作流日志，而不是先更改请求负载。
如果 invoke 请求本身立即返回了 `error` 对象，请先修复该请求，然后再花时间调试工作流编辑器。
另请参阅：[使用 API 运行](./run-with-api)、[回调投递与 Webhook 触发](./async-and-webhooks) 和 [日志](./logs)