> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码说明

> 了解 xParse Pipeline 接口的错误码和常见错误信息

[Pipeline 接口](/api-reference/endpoint/pipeline)可能返回以下错误码：

* **200**: 成功
* **400**: 请求参数错误（BadRequest）
* **40101**: x-ti-app-id或x-ti-secret-code为空
* **40102**: x-ti-app-id或x-ti-secret-code错误
* **40004**: 参数验证失败（InvalidParams）
* **500**: 服务器内部错误（InternalServerError）

## 错误信息分类

### 鉴权错误

| 错误码   | 错误信息                           | 触发条件                              |
| ----- | ------------------------------ | --------------------------------- |
| 40101 | x-ti-app-id或x-ti-secret-code为空 | x-ti-app-id或x-ti-secret-code为空时返回 |
| 40102 | x-ti-app-id或x-ti-secret-code错误 | x-ti-app-id或x-ti-secret-code无效时返回 |

### 参数校验阶段错误（CheckParams）

#### 1. 文件相关错误（错误码: 400）

| 错误信息                     | 触发条件                |
| ------------------------ | ------------------- |
| `缺少必要参数或参数值不正确：获取文件失败`   | 无法从 form-data 中获取文件 |
| `缺少必要参数或参数值不正确：无法读取文件`   | 无法打开文件              |
| `缺少必要参数或参数值不正确：读取文件信息失败` | 无法读取文件内容            |

#### 2. 配置解析错误（错误码: 400）

| 错误信息                                 | 触发条件                           |
| ------------------------------------ | ------------------------------ |
| `缺少必要参数或参数值不正确：stages 配置缺失`          | stages 参数为空                    |
| `缺少必要参数或参数值不正确：解析 stages 配置失败`       | stages JSON 解析失败               |
| `缺少必要参数或参数值不正确：解析 config 配置失败`       | config JSON 解析失败               |
| `缺少必要参数或参数值不正确：解析 data_source 配置失败`  | data\_source JSON 解析失败         |
| `缺少必要参数或参数值不正确：解析 embed 配置失败：<具体错误>` | embed stage 的 config JSON 解析失败 |

#### 3. 配置验证错误（错误码: 40004）

| 错误信息                                                          | 触发条件                 |
| ------------------------------------------------------------- | -------------------- |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：stages 配置不能为空`                  | stages 数组为空          |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：stages 配置长度不能超过3，当前值：<N>`       | stages 数量超过 3 个      |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：第一个 stage 必须是 parse，当前值：<type>` | 第一个 stage 不是 parse   |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：parse stage 必须出现一次，当前值：<N>`     | parse stage 数量不等于 1  |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：chunk stage 最多出现一次，当前值：<N>`     | chunk stage 数量大于 1   |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：embed stage 最多出现一次，当前值：<N>`     | embed stage 数量大于 1   |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：chunk stage 必须在 embed stage 之前` | chunk 在 embed 之后     |
| `缺少必要参数或参数值不正确：验证 stages 配置失败：embed stage 必须在 parse 之后`       | embed 是第一个 stage     |
| `缺少必要参数或参数值不正确：验证 embed 配置失败：provider 不能为空`                   | embed provider 为空    |
| `缺少必要参数或参数值不正确：验证 embed 配置失败：model_name 不能为空`                 | embed model\_name 为空 |
| `缺少必要参数或参数值不正确：验证 embed 配置失败：不支持的 provider`                   | embed provider 不支持   |
| `缺少必要参数或参数值不正确：验证 embed 配置失败：不支持的 model`                      | embed model 不支持      |

### 执行阶段错误（Handle）

#### 1. Stage Runner 创建错误（错误码: 400）

| 错误信息                               | 触发条件                                |
| ---------------------------------- | ----------------------------------- |
| `缺少必要参数或参数值不正确：创建 stage runner 失败` | stage type 未知（不是 parse/chunk/embed） |

#### 2. Stage 执行错误（错误码: 500）

最终返回格式为：
`服务器内部错误：stage <stage type> 执行失败：<核心错误信息>`

##### Parse Stage 错误

| 核心错误信息                | 触发条件                                      |
| --------------------- | ----------------------------------------- |
| `读取文件失败`              | 无法读取文件内容                                  |
| `创建请求失败`              | 无法创建 multipart form file                  |
| `写入请求信息失败`            | 无法写入文件到 form                              |
| `数据源信息格式错误`           | data\_source JSON 序列化失败                   |
| `配置信息格式错误`            | config JSON 序列化失败                         |
| `发送请求失败`              | HTTP 请求发送失败                               |
| `请求失败`                | HTTP 状态码不是 200                            |
| `解析响应失败`              | 响应 JSON 解析失败                              |
| `<parseResp.Message>` | parse 服务返回的业务错误（Code != 200），直接透传 message |

##### Chunk Stage 错误

| 核心错误信息                | 触发条件                                      |
| --------------------- | ----------------------------------------- |
| `序列化请求失败`             | 请求 JSON 序列化失败                             |
| `发送请求失败`              | HTTP 请求发送失败                               |
| `请求失败`                | HTTP 状态码不是 200                            |
| `解析响应失败`              | 响应 JSON 解析失败                              |
| `<chunkResp.Message>` | chunk 服务返回的业务错误（Code != 200），直接透传 message |

##### Embed Stage 错误

| 核心错误信息         | 触发条件                                     |
| -------------- | ---------------------------------------- |
| `embed配置为空`    | embed config 为 nil                       |
| `不支持的embed提供商` | provider 不是 qwen 或 doubao                |
| `请求失败`         | embed provider 客户端未初始化 或 OpenAI API 调用失败 |

## 错误信息格式说明

### 错误信息拼接规则

1. **参数校验阶段**：使用 `BizStatusWrap` 函数，格式为 `基础错误信息: 具体错误信息`
   * 例如：`缺少必要参数或参数值不正确: stages 配置缺失`

2. **执行阶段**：使用 `BizStatusWrap` 函数，格式为 `服务器内部错误: <核心错误信息>`
   * 核心错误信息(包括引擎返回报错)直接透传
   * 例如：`服务器内部错误: 请求失败`

## 示例

### 示例 1：参数错误

```json theme={null}
{
  "code": 400,
  "message": "缺少必要参数或参数值不正确：stages 配置缺失"
}
```

### 示例 2：配置验证错误

```json theme={null}
{
  "code": 40004,
  "message": "缺少必要参数或参数值不正确：验证 stages 配置失败：第一个 stage 必须是 parse，当前值：chunk"
}
```

### 示例 3：Parse Stage 执行错误

```json theme={null}
{
  "code": 500,
  "message": "服务器内部错误：stage parse 执行失败：请求失败"
}
```

### 示例 4：Parse Stage 业务错误（透传服务端 message）

```json theme={null}
{
  "code": 500,
  "message": "服务器内部错误：stage parse 执行失败：不支持的provider: texti"
}
```

### 示例 5：Embed Stage 配置错误

```json theme={null}
{
  "code": 500,
  "message": "服务器内部错误：stage embed 执行失败：不支持的embed提供商" // 这里其实会被提前检出
}
```