# 错误 (/docs/api/native/knowledge/errors)



| HTTP | code                          | 处理建议                                        |
| ---- | ----------------------------- | ------------------------------------------- |
| 400  | INVALID\_PARAMS               | 字段、筛选条件或分页参数无效。                             |
| 400  | LIMIT\_EXCEEDED               | 超过容量或批次上限。                                  |
| 401  | UNAUTHENTICATED               | 检查 API Key；兼容响应 code 为 null。                |
| 404  | VECTOR\_STORE\_NOT\_FOUND     | 知识库不存在或不可访问。                                |
| 404  | FILE\_NOT\_FOUND              | 源文件不存在。                                     |
| 404  | FILE\_NOT\_IN\_STORE          | 文件未加入此知识库。                                  |
| 404  | BATCH\_NOT\_FOUND             | 批次不存在。                                      |
| 404  | CHUNK\_NOT\_FOUND             | 分段不存在。                                      |
| 409  | VECTOR\_STORE\_INVALID\_STATE | 知识库当前状态不允许该操作。                              |
| 409  | FILE\_INVALID\_STATE          | 仅 failed 文件可以重试。                            |
| 413  | PAYLOAD\_TOO\_LARGE           | JSON 请求超过 1,000,000 字节；兼容响应的 code 可能为 null。 |
| 429  | RATE\_LIMITED                 | 稍后重试。                                       |
| 500  | — / null                      | 服务内部错误；保留请求 ID 并稍后重试。                       |
| 501  | NOT\_IMPLEMENTED              | 操作尚未实现。                                     |
| 503  | PROVIDER\_UNAVAILABLE         | 处理服务暂不可用，可稍后重试。                             |

## 原生 API 错误对象 [#原生-api-错误对象]

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| error | object | 必有 |
| error.code | "INVALID_PARAMS" / "LIMIT_EXCEEDED" / "UNAUTHENTICATED" / "VECTOR_STORE_NOT_FOUND" / "FILE_NOT_FOUND" / "FILE_NOT_IN_STORE" / "BATCH_NOT_FOUND" / "CHUNK_NOT_FOUND" / "VECTOR_STORE_INVALID_STATE" / "FILE_INVALID_STATE" / "PAYLOAD_TOO_LARGE" / "RATE_LIMITED" / "NOT_IMPLEMENTED" / "PROVIDER_UNAVAILABLE" | 可选 |
| error.message | string | 必有 |
| error.details | string / null | 可选 |

## OpenAI 兼容错误对象 [#openai-兼容错误对象]

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| error | object | 必有 |
| error.message | string | 必有 |
| error.type | "invalid_request_error" / "not_found_error" / "rate_limit_error" / "server_error" | 必有 |
| error.param | string / null | 必有 |
| error.code | "INVALID_PARAMS" / "LIMIT_EXCEEDED" / "UNAUTHENTICATED" / "VECTOR_STORE_NOT_FOUND" / "FILE_NOT_FOUND" / "FILE_NOT_IN_STORE" / "BATCH_NOT_FOUND" / "CHUNK_NOT_FOUND" / "VECTOR_STORE_INVALID_STATE" / "FILE_INVALID_STATE" / "PAYLOAD_TOO_LARGE" / "RATE_LIMITED" / "NOT_IMPLEMENTED" / "PROVIDER_UNAVAILABLE" / null | 必有 |

未知路径的 404 可能只有 error.message；401 可能没有 details，兼容接口的 413 可能返回 code: null。路径编码错误也可能返回 HTML。不要假定每个失败都有业务错误码。

## 异步文件错误 [#异步文件错误]

添加文件成功并不表示内容已可搜索。检查文件 status；failed 时读取 last\_error。

| last\_error.code  | 含义                       | 建议                       |
| ----------------- | ------------------------ | ------------------------ |
| unsupported\_file | 解析器不支持该文件                | 转换为 TXT、Markdown 或已验证的格式 |
| invalid\_file     | 内容无效、为空、加密或超过估算 token 上限 | 检查内容、解密或拆分文件             |
| server\_error     | 处理失败或超过 30 分钟截止时间        | 稍后用 retry 重试失败文件         |