错误码
错误响应格式
PDF 处理服务的错误响应使用以下 JSON 结构：
json
{
"code": 110001,
"message": "page range out of bounds: 0-99",
"traceId": "a1b2c3d4e5f6..."
}| 字段 | 类型 | 说明 |
|---|---|---|
code | Integer | 6 位数字错误码，作为程序判断依据 |
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 | 权限不足 |
PDF 功能错误码
此部分错误码来源于 PDF 处理服务。
100xxx — 通用请求与文件错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
100001 | INVALID_ARGUMENT | 400 | 请求参数缺失、类型错误或枚举值非法 |
100002 | INVALID_JSON | 400 | 请求 JSON 解析失败 |
100003 | CONFLICTING_ARGUMENTS | 400 | 互斥参数同时出现 |
100101 | INVALID_FILE_TYPE | 400 | 上传文件类型不符合接口要求 |
100102 | FILE_REQUIRED | 400 | 缺少必须的文件字段 |
100103 | FILE_COUNT_MISMATCH | 400 | 多文件与参数数组数量不一致 |
100104 | FILE_TOO_LARGE | 413 | 文件体积超出服务端限制 |
100106 | INVALID_OUTPUT_FILE_NAME | 400 | 输出文件名非法 |
110xxx — 页面与坐标错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
110001 | INVALID_PAGE_RANGE | 400 | 页码范围非法或页码越界 |
110002 | INVALID_PAGE_INDEX | 400 | 页索引为负数或超出文档页数 |
110003 | INVALID_RECT | 400 | 矩形参数不合法 |
110005 | PAGE_RANGE_EMPTY | 400 | 解析后没有可处理的页面 |
120xxx — 密码与证书错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
120001 | PASSWORD_REQUIRED | 400 | 文档已加密但未提供密码 |
120002 | INVALID_PASSWORD | 400 | PDF 密码错误 |
120101 | CERTIFICATE_INVALID | 400 | 证书文件无法解析或格式不支持 |
120102 | CERTIFICATE_PASSWORD_REQUIRED | 400 | 证书需要密码但未提供 |
120103 | CERTIFICATE_PASSWORD_INVALID | 400 | 证书密码错误 |
120201 | ICC_PROFILE_REQUIRED | 400 | 标准化转换缺少 ICC 文件 |
130xxx — 业务状态错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
130002 | UNSUPPORTED_ENUM_VALUE | 400 | 枚举值不在允许范围内 |
130101 | SIGNATURE_NOT_FOUND | 404 | 指定签名不存在 |
130102 | WATERMARK_NOT_FOUND | 404 | 指定水印不存在 |
130103 | BACKGROUND_NOT_FOUND | 404 | 文档中不存在可操作背景 |
130104 | HEADER_FOOTER_NOT_FOUND | 404 | 文档中不存在页眉页脚配置 |
130105 | BATES_NOT_FOUND | 404 | 文档中不存在 Bates 编号 |
130106 | REDACTION_NOT_FOUND | 404 | 未找到可应用的密文标记 |
130107 | NO_CHANGES_DETECTED | 422 | 操作执行成功但无变更产出 |
190xxx — 处理与系统错误
| 错误码 | 语义标识 | HTTP | 说明 |
|---|---|---|---|
190001 | PROCESS_FAILED | 500 | 服务处理失败（文档打开/保存/操作执行错误） |
190002 | TEMP_FILE_WRITE_FAILED | 500 | 临时文件写入失败 |
190003 | TEMP_FILE_READ_FAILED | 500 | 临时文件读取失败 |
190004 | RESULT_PACKAGE_FAILED | 500 | 多文件结果打包失败 |
190999 | INTERNAL_ERROR | 500 | 未归类的服务内部错误 |
重试建议
| 错误码范围 | 是否可重试 | 建议 |
|---|---|---|
100xxx | 不可重试 | 修正请求参数或文件后重新提交 |
110xxx | 不可重试 | 修正页码或坐标后重新提交 |
120xxx | 不可重试 | 修正密码或证书后重新提交 |
130xxx | 不可重试 | 资源不存在或业务状态异常，修正请求 |
190xxx（不含 190999） | 建议重试 | 服务处理问题，退避重试（最多 3 次） |
190999 | 建议重试 | 内部错误，退避重试 |
06001 | 不可重试 | 购买套餐后继续使用 |
01xxx、02xxx、04xxx | 不可重试 | 修正文件或参数后重试 |