# 任务状态、错误与恢复

AI Studio SDK 没有通用的等待完成或自动重试操作。工作流运行、导入任务、导出任务、智能体任务和 SQL 查询各自提供状态读取、取消或重试入口；等待时间、轮询间隔和是否再次执行由调用方决定。

(sdk-ai-studio-async-task-flow)=
## 任务流程

1. 对返回任务或运行 ID 的操作，保存服务端返回的 ID。
2. 使用同一资源类型读取状态或结果。
3. 只根据该资源返回的状态和结果决定后续操作。

本地等待到期只表示应用停止等待，不表示平台已经停止任务。重新提交可能写入数据或创建资源的请求前，先读取原任务状态。

(sdk-ai-studio-async-task-resource-actions)=
## 使用资源专属的恢复操作

重试和取消是资源专属操作，并不等同于自动重试网络请求。

| 资源 | 可用操作 | 调用前检查 |
| --- | --- | --- |
| 工作流运行 | 重试、取消 | 使用运行 ID 读取当前运行和结果，确认是否继续。 |
| 导入任务 | 重试失败文件、暂停、恢复 | 先读取任务、运行或失败文件；只选择需要重试的文件。 |
| 导出任务 | 重试失败文件 | 先读取任务详情和运行状态；只选择需要重试的文件。 |
| SQL 查询 | 取消 | 先读取查询状态；已结束查询的取消可能被拒绝。 |

(sdk-ai-studio-async-task-errors)=
## 处理 SDK 错误

认证、权限、参数校验、资源不存在或作用域不匹配时，先修正问题，不要自动重试。发生网络错误或本地超时时，先用已保存的 ID 读取原资源状态，再决定是否进行资源专属重试或重新提交。

Go 和 Python 的 SDK 错误都提供错误代码、错误消息、状态和请求标识。请求标识仅来自响应头；响应正文中的同名字段不会作为传输请求标识使用。记录诊断信息时不要记录访问令牌、连接器密钥、文件内容或完整业务负载。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Go
:sync: go

```go
import (
	"errors"
	"log"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func logSDKError(err error) {
	var productErr *sdk.Error
	if errors.As(err, &productErr) {
		log.Printf(
			"AI Studio SDK request failed: code=%s status=%d request_id=%s message=%s",
			productErr.Code, productErr.Status, productErr.RequestID, productErr.Message,
		)
		return
	}
	log.Printf("AI Studio SDK request failed: %v", err)
}
```

::::

::::{tab-item} Python
:sync: python

```python
import logging

import moi_product_sdk as sdk


def log_sdk_error(operation):
    try:
        return operation()
    except sdk.Error as error:
        logging.error(
            "AI Studio SDK request failed: code=%s status=%s request_id=%s message=%s",
            error.code,
            error.status,
            error.request_id,
            error.message,
        )
        raise
```

::::

:::::

(sdk-ai-studio-async-task-streams)=
## 流式响应和本地超时

流式调用、文件预览和下载返回的是正在读取的响应，不是任务完成信号。Go 调用方在读取后关闭响应体；Python 调用方关闭流式响应。如果应用设置了本地超时或停止读取流，请通过相应任务或运行对象查询实际状态。

(sdk-ai-studio-async-task-next)=
## 下一步

- [连接器、导入与导出任务](guides/connectors-import-export.md)
- [部署和控制工作流](guides/workflow-runtime.md)
- [智能体调用和任务查询](guides/agents-a2a.md)