接口错误码

请求失败时，ComPDF Self-hosted 返回统一错误响应。转档和 PDF 处理错误统一使用 HTTP 200，并在 JSON 中保留相应的业务错误；ComPDF Self-hosted 自身产生的错误仍使用对应的 4xx 或 5xx HTTP 状态。

type 字段用于标识错误码所属的来源。处理错误时必须同时使用 type 与 code 或 errorCode：转档处理引擎与 PDF SDK 会复用部分数值错误码，但含义不同。转档 SDK 原始错误可以使用 4 等短数字错误码，API 与 server 错误通常使用六位数字业务码。

json

{
  "type": "conversion",
  "code": 4,
  "errorCode": "PDF_PAGE_ERROR",
  "message": "PDF page failed to load.",
  "traceId": "82f733c63cc74946a7c5671430e3c6a4"
}

字段说明

字段	类型	说明
`type`	String	错误来源：`conversion`、`pdf` 或 `server`。
`code`	Number	来源返回的数字错误码。转档 SDK 错误可以使用原始 SDK 错误码，API 与 server 错误通常使用六位数字业务码。
`errorCode`	String	与 `code` 对应的稳定语义错误标识。
`message`	String	英文可读错误信息。已文档化的处理错误使用对应 SDK 错误定义中的英文说明。
`traceId`	String	用于关联请求和服务日志的追踪 ID。

错误来源与重复错误码

`type`	来源	`errorCode` 处理方式
`conversion`	转档处理	标识转档处理错误。
`pdf`	PDF 处理	标识 PDF 处理错误。
`server`	ComPDF Self-hosted	错误由 ComPDF Self-hosted 自身产生，并使用 Server 错误码定义。

同一个数字错误码在不同来源中可能代表不同含义。例如 120001 在 type: "conversion" 中表示 AUTH_REQUIRED，在 type: "pdf" 中表示 PASSWORD_REQUIRED。同样，190005 在转档中表示 OCR_FAILURE，在 PDF 处理中表示 RESOURCE_EXHAUSTED。

ComPDF Web 使用 type 和 errorCode 显示本地化错误提示。API 调用方也应使用这些稳定字段进行程序处理，而不应解析 message 文本。

常见错误码

HTTP 状态	`code`	`errorCode`	含义
`200`	处理错误码	处理 `errorCode`	转档或 PDF 处理发生业务错误。通过 `type` 区分 `conversion` 与 `pdf`。
`400`	`100001`	`BAD_REQUEST` / `VALIDATION_ERROR`	server 请求参数缺失或无效。
`401`	`140001`	`UNAUTHORIZED`	缺少或传入了无效的 `x-api-key` / 管理端会话。
`403`	`140002`	`FORBIDDEN` / `INVALID_TOKEN`	当前请求无权执行。
`404`	`150001`	`NOT_FOUND`	资源或任务不存在。
`409`	`150002` / `150003`	`TASK_NOT_READY` / `CONFLICT` / `INVALID_STATE`	任务或资源状态不允许当前请求。
`413`	`100104`	`FILE_TOO_LARGE`	文件在进入底层处理前超过 ComPDF Self-hosted 请求限制。
`429`	`130012`	`CONCURRENCY_LIMIT`	同时到达 ComPDF Self-hosted 的请求过多。
`500`	`190999`	`INTERNAL_ERROR`	未预期的 server 错误。

请求示例

bash

curl -X POST "http://localhost:8080/api/v1/process/pdf/docx" \
  -H "x-api-key: your_api_key_here" \
  -F "file=@/path/to/sample.pdf" \
  -F 'options={"pageRanges":"999999"}'

处理引擎业务码

本表中的所有处理错误均使用 HTTP 200 返回。转档错误目录包含 4（PDF_PAGE_ERROR）等原始数字错误码及六位转档 API 错误码。解释重复数值前请先确认对应的 type。

`code`	`errorCode`	含义
`100001`	`INVALID_REQUEST`（`conversion`）/ `INVALID_ARGUMENT`（`pdf`）	请求或参数无效。
`100002`	`INVALID_JSON`	`request` 或 `options` 不是合法 JSON。
`100101`	`INVALID_FILE_TYPE`	上传文件类型不支持。
`100102`	`FILE_REQUIRED`	缺少必须的文件字段。
`100103`	`FILE_COUNT_MISMATCH`	文件数量和参数不匹配。
`100104`	`FILE_TOO_LARGE`	上传文件超过大小限制。
`100105`	`PAGE_LIMIT_EXCEEDED`	超过页面数量限制。
`100106`	`INVALID_OUTPUT_FILE_NAME`	输出文件名非法。
`110001`	`INVALID_PAGE_RANGE`	页码范围非法。
`110002`	`INVALID_PAGE_INDEX`	页面索引非法。
`110003`	`INVALID_RECT`	矩形参数非法。
`110004`	`INVALID_QUAD_RECTS`	多区域坐标参数非法。
`110005`	`PAGE_RANGE_EMPTY`	页码范围未命中页面。
`120001`	`AUTH_REQUIRED`（`conversion`）/ `PASSWORD_REQUIRED`（`pdf`）	转档需要认证；PDF 处理需要密码。
`120002`	`INVALID_TOKEN`（`conversion`）/ `INVALID_PASSWORD`（`pdf`）	转档 Token 无效；PDF 处理密码错误。
`120201`	`ICC_PROFILE_REQUIRED`	缺少 ICC profile 文件。
`120202`	`ICC_PROFILE_INVALID`	ICC profile 文件无效。
`130003`	`INVALID_STATE`	当前任务状态不允许操作。
`190001`	`CONVERT_FAILED`（`conversion`）/ `SDK_PROCESS_FAILED`（`pdf`）	转档或 SDK 处理失败。
`190002`	`PDF_PASSWORD_ERROR`（`conversion`）/ `TEMP_FILE_WRITE_FAILED`（`pdf`）	转档密码错误；PDF 处理临时文件写入失败。
`190003`	`PDF_FORMAT_ERROR`（`conversion`）/ `TEMP_FILE_READ_FAILED`（`pdf`）	转档 PDF 格式错误；PDF 处理临时文件读取失败。
`190004`	`PDF_SECURITY_ERROR`（`conversion`）/ `RESULT_PACKAGE_FAILED`（`pdf`）	转档 PDF 安全错误；PDF 处理结果打包失败。
`190005`	`OCR_FAILURE`（`conversion`）/ `RESOURCE_EXHAUSTED`（`pdf`）	转档 OCR 失败；PDF 处理资源不足。
`190006`	`JOB_TIMEOUT`（`conversion`）/ `REQUEST_TIMEOUT`（`pdf`）	转档任务超时或 PDF 处理请求超时。
`190009`	`SDK_FILE_ERROR`	文件无法打开或不存在。
`190999`	`UPSTREAM_ERROR`	未知处理引擎错误。

接口错误码 ​

字段说明 ​

错误来源与重复错误码 ​

常见错误码 ​