错误码
错误响应格式
AI 服务的错误响应使用以下 JSON 结构：
json
{
"success": false,
"error_code": "DOWNLOAD_TIMEOUT",
"code": 200002,
"message": "Human-readable description",
"detail": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
code | Integer | 6 位数字错误码，作为程序判断依据 |
error_code | String | 语义化错误标识，仅用于可读性参考 |
message | String | 错误描述 |
detail | Object | 补充上下文（可选） |
基础服务错误码
此类错误码由服务框架统一处理，适用于所有 ComPDF API 接口。
01xxx — 系统异常
| 错误码 | HTTP | 说明 |
|---|---|---|
01001 | 500 | 系统内部错误 |
01002 | 500 | 处理后文件上传至存储服务失败 |
01003 | 500 | 文件上传异常 |
01004 | 500 | 无法下载您上传的文件 |
01005 | 400 | 文件不能为空 |
01006 | 400 | 请求参数无效，请设置有效的文件参数 |
01007 | 400 | 任务 ID 不能为空 |
02xxx — 文件格式异常
| 错误码 | HTTP | 说明 |
|---|---|---|
02001 | 400 | 文件格式错误 |
02002 | 400 | 不支持转换该格式的文件 |
02003 | 400 | 不支持的图片格式 |
02201 | 400 | 文件存在加密 |
02207 | 400 | 文件打开失败：文件类型不支持或存在加密 |
02209 | 413 | 文件过大，请上传较小的文件 |
02210 | 500 | 文件处理失败 |
02212 | 500 | 文件处理失败：处理后文件大小异常 |
03000 — 参数校验异常
| 错误码 | HTTP | 说明 |
|---|---|---|
03000 | 400 | 参数校验失败，通常在请求缺少必填字段或字段格式不符合要求时触发 |
04xxx — 文件与业务异常
| 错误码 | HTTP | 说明 |
|---|---|---|
04001 | 400 | 文件 Key 不存在 |
04002 | 400 | 文件大小为 0 |
04003 | 400 | 文件不存在或无法打开 |
04007 | 400 | 该接口只允许上传一个文件 |
04008 | 400 | 合并 PDF 最多支持 5 个文件 |
05xxx — 任务异常
| 错误码 | HTTP | 说明 |
|---|---|---|
05001 | 404 | 任务不存在或无效 |
05002 | 409 | 任务状态异常 |
05003 | 400 | 单个任务处理的文件数已到达阈值 |
05004 | 410 | 任务已过期且未执行 |
05005 | 400 | 任务必须包含至少一个文件 |
06001 — 资产不足
| 错误码 | HTTP | 说明 |
|---|---|---|
06001 | 402 | 可处理的页数额度已用完，请购买套餐后继续使用 |
认证与权限
| HTTP | 错误码 | 说明 |
|---|---|---|
401 | 401 | API Key 无效或未提供；认证服务不可用 |
403 | 403 | 权限不足 |
AI 功能错误码
此部分错误码来源于 AI 文档解析与抽取服务。
100xxx — 请求参数校验
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
100001 | INVALID_REQUEST | 400 | 请求格式错误 |
100003 | INVALID_JSON | 400 | JSON 解析失败 |
100004 | INVALID_CONTENT_FILTER | 400 | 不支持的 content_filter 值 |
100005 | INVALID_EXTRACT_MODE | 400 | 不支持的抽取模式 |
100006 | MISSING_FILE | 400 | 缺少文件参数 |
100008 | MISSING_EXTRACT_FIELDS | 400 | 缺少 extract_fields 参数 |
200xxx — 文件下载
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
200001 | DOWNLOAD_FAILED | 502 | 文件下载失败 |
200002 | DOWNLOAD_TIMEOUT | 504 | 下载请求超时 |
200003 | DOWNLOAD_TOO_LARGE | 413 | 文件超出配置的最大大小 |
200009 | DOWNLOAD_SERVER_DISCONNECTED | 502 | 远程服务器意外断开连接 |
300xxx — 文档解析
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
300001 | PARSE_FAILED | 500 | 解析执行失败 |
300002 | PARSE_TIMEOUT | 504 | 解析请求超时 |
300003 | PARSE_PIPELINE_ERROR | 502 | 解析服务返回错误 |
300009 | PARSE_FILE_TOO_LARGE | 413 | 文件超出解析大小限制 |
400xxx — 字段抽取
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
400001 | EXTRACT_FAILED | 500 | 抽取失败 |
400002 | EXTRACT_TIMEOUT | 504 | 抽取请求超时 |
400003 | EXTRACT_VLM_ERROR | 502 | VLM 服务返回错误 |
400004 | EXTRACT_LLM_ERROR | 502 | LLM 服务返回错误 |
400005 | EXTRACT_INVALID_SCHEMA | 400 | extract_fields schema 无效 |
400006 | EXTRACT_IMAGE_LOAD_FAILED | 500 | 图片或 PDF 加载失败 |
500xxx — 对象存储
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
500003 | STORAGE_UPLOAD_FAILED | 500 | 上传至存储服务失败 |
500004 | STORAGE_DOWNLOAD_FAILED | 500 | 从存储服务下载失败 |
500006 | STORAGE_OBJECT_NOT_FOUND | 404 | 存储中未找到目标文件 |
600xxx — 异步任务
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
600001 | TASK_NOT_FOUND | 404 | 任务不存在 |
600002 | TASK_ALREADY_COMPLETED | 400 | 任务已完成 |
600003 | TASK_ALREADY_CANCELLED | 400 | 任务已取消 |
600005 | TASK_RESULT_NOT_FOUND | 404 | 任务结果不存在 |
600006 | TASK_EXPIRED | 410 | 任务已过期 |
600007 | TASK_CREATE_FAILED | 500 | 创建任务失败 |
700xxx — 数据库
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
700001 | DB_CONNECT_FAILED | 500 | 数据库连接失败 |
700002 | DB_TIMEOUT | 504 | 数据库操作超时 |
700003 | DB_QUERY_FAILED | 500 | 数据库查询失败 |
900xxx — 系统级错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
900001 | INTERNAL_ERROR | 500 | 服务内部错误 |
900003 | SERVICE_UNAVAILABLE | 503 | 服务暂不可用 |
900005 | DEPENDENCY_UNAVAILABLE | 503 | 依赖服务不可用 |
重试建议
| 错误码范围 | 是否可重试 | 建议 |
|---|---|---|
100xxx、400005 | 不可重试 | 修正请求参数后重新提交 |
200xxx | 建议重试 | 文件下载类问题，退避重试 |
300xxx、400xxx（除 400005） | 建议重试 | 服务处理问题，退避重试 |
500xxx、700xxx、900xxx | 可重试 | 服务端临时问题，间隔重试 |
600xxx | 视情况 | TASK_NOT_FOUND 等不可重试，超时可重新创建任务 |
06001 | 不可重试 | 购买套餐后继续 |
01xxx、02xxx、04xxx | 不可重试 | 修正文件或参数后重试 |