知识库
错误
HTTP 错误码与异步入库失败。
| 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 错误对象
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 兼容错误对象
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 重试失败文件 |