错误码
错误响应格式
Conversion 服务的错误响应使用以下 JSON 结构：
json
{
"code": 100104,
"errorCode": "FILE_TOO_LARGE",
"message": "Human-readable description",
"traceId": "a1b2c3d4e5f6..."
}| 字段 | 类型 | 说明 |
|---|---|---|
code | Integer | 数字错误码，作为程序判断依据 |
errorCode | String | 语义化错误标识，仅用于可读性参考 |
message | String | 错误描述 |
traceId | String | 全链路追踪 ID |
基础服务错误码
此类错误码由服务框架统一处理，适用于所有 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 | 权限不足 |
Conversion 功能错误码
此部分错误码来源于文档转换服务。
100xxx — 通用请求与文件错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
100001 | INVALID_REQUEST | 400 | 参数缺失或格式错误 |
100101 | INVALID_FILE_TYPE | 415 | 上传的文件不是 PDF |
100104 | FILE_TOO_LARGE | 413 | 文件大小超过同步接口限制，请使用异步接口 |
100105 | PAGE_LIMIT_EXCEEDED | 422 | PDF 页数超过限制 |
120xxx — 鉴权错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
120001 | AUTH_REQUIRED | 401 | 未携带认证凭证 |
120002 | INVALID_TOKEN | 403 | 认证凭证无效或已过期 |
130xxx — 业务状态错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
130001 | NOT_FOUND | 404/410 | 文档或任务不存在，或结果文件已被清理 |
130002 | JOB_NOT_READY | 409 | 任务未完成，不可下载 |
130003 | INVALID_STATE | 409 | 任务已处于终态，无法取消 |
130004 | IDEMPOTENCY_IN_PROGRESS | 409 | 相同幂等键的请求正在处理中 |
190xxx — 处理与系统错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
190001 | CONVERT_FAILED | 500 | 文档转换处理失败（文件损坏或服务内部错误） |
190002 | PDF_PASSWORD_ERROR | 422 | PDF 密码错误或缺失 |
190003 | PDF_FORMAT_ERROR | 400 | PDF 格式无效或文件损坏 |
190004 | PDF_SECURITY_ERROR | 400 | PDF 使用了不支持的加密方式 |
190005 | OCR_FAILURE | 500 | OCR 识别失败 |
190006 | JOB_TIMEOUT | 408 | 转换处理超时 |
190007 | NO_TABLE | 422 | 源文件中未找到表格 |
190008 | OUT_OF_MEMORY | 500 | 处理过程中内存不足，建议减小文件 |
190009 | FILE_ERROR | 400 | 文件无法打开或不存在 |
190010 | IMAGE_INVALID | 400 | 图片无效、损坏或格式不支持 |
190999 | INTERNAL_ERROR | 500/503 | 服务内部错误或依赖服务未就绪 |
重试建议
| 错误码范围 | 是否可重试 | 建议 |
|---|---|---|
100xxx | 不可重试 | 修正请求参数或文件后重新提交 |
120xxx | 不可重试 | 修正认证凭证后重新提交 |
130001–130004 | 视情况 | 资源不存在类不可重试，状态冲突可查询后再试 |
190001–190010 | 建议重试 | 服务处理类问题，退避重试（最多 3 次） |
190999 | 建议重试 | 内部错误，退避重试 |
06001 | 不可重试 | 购买套餐后继续使用 |
01xxx、02xxx、04xxx | 不可重试 | 修正文件或参数后重试 |