---
name: seacloud-errors
description: 当智能体需要处理 @seacloudai/sdk 错误、捕获 SeaCloudError，或区分 AuthError、BalanceError、ValidationError、ModelNotFoundError、TaskTimeoutError、NetworkError、TimeoutError 时使用。
---

# SeaCloud 错误

使用 `isSeaCloudError` 捕获 SDK 错误。

```ts
import { isSeaCloudError } from "@seacloudai/sdk";

try {
  await client.runSync("kling_v2_6_i2v", {
    prompt: "海上云层",
    duration: 5,
  });
} catch (error) {
  if (isSeaCloudError(error)) {
    console.error(error.type, error.message, error.hint);
  }
  throw error;
}
```

## 错误类型

- `AuthError`：API key 缺失、无效或已过期。
- `BalanceError`：账户余额不足。
- `ValidationError`：SDK 基础参数或契约规划无效；查看 `modelId` 和 `parameter`。例如缺少 `input_schema.required` 声明的顶层字段。其他模型业务参数错误通常由接口以 HTTP 错误返回。
- `ModelNotFoundError`：模型合约查询失败或模型不存在。
- `TaskTimeoutError`：`runSync` 等待任务完成超时；查看 `taskId`，并用 `tasks.get` 重试查询。
- `NetworkError`：请求在获得有效 HTTP 响应前失败，或后端返回未映射的 HTTP 错误。
- `TimeoutError`：单次 HTTP 请求超时。

## 任务失败

`runSync` 拿到任务失败状态时返回稳定结果，不抛 `TaskFailedError`：

```ts
const result = await client.runSync("gpt_image_2", params);

if (result.status === "failed") {
  console.error(result.error?.message);
}
```