接口错误码

JSON 请求失败时，ComPDF Self-hosted 返回统一错误响应。若 PDF SDK 或转档处理引擎返回数字业务码，服务会保留为 bizCode，并在可映射时返回对应的语义 errorCode。

{
  "code": "400",
  "msg": "pageRanges contains an invalid page index",
  "data": null,
  "errorCode": "INVALID_PAGE_RANGE",
  "bizCode": 110001,
  "traceId": "3a5d0d2c1a0f4a4b"
}

字段说明

字段	类型	说明
code	String	HTTP 状态码字符串。
msg	String	可读错误信息。
data	Null	错误响应中固定为 null。
errorCode	String	本地或处理引擎语义错误码。
bizCode	Number	处理引擎数字业务码，可用时返回。
traceId	String	追踪 ID，可用时返回。
details	Any	参数校验详情或额外诊断信息。

常见错误码

HTTP 状态	errorCode	含义
400	BAD_REQUEST / VALIDATION_ERROR / INVALID_REQUEST / INVALID_ARGUMENT	请求参数缺失或无效。
401	UNAUTHORIZED	缺少或传入了无效的 x-api-key / 管理端会话。
403	FORBIDDEN / INVALID_TOKEN	已认证但无权限执行该请求，或上游处理服务 token 无效。
404	NOT_FOUND	资源或任务不存在。
409	TASK_NOT_READY / INVALID_STATE	任务未准备好，或任务状态不允许当前操作。
413	FILE_TOO_LARGE	上传文件超过大小限制。
429	CONCURRENCY_EXCEEDED / CONCURRENCY_LIMIT	并发请求过多。
500	INTERNAL_ERROR	未预期的服务端错误。
502	UPSTREAM_ERROR	文件处理服务返回错误或超时。

请求示例

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"}'

处理引擎业务码

bizCode	errorCode	含义
100001	INVALID_REQUEST / INVALID_ARGUMENT	请求或参数无效。
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	PASSWORD_REQUIRED	需要密码。
120002	INVALID_PASSWORD	密码错误。
120201	ICC_PROFILE_REQUIRED	缺少 ICC profile 文件。
120202	ICC_PROFILE_INVALID	ICC profile 文件无效。
130003	INVALID_STATE	当前任务状态不允许操作。
190001	CONVERT_FAILED / SDK_PROCESS_FAILED	转换或 SDK 处理失败。
190002	PDF_PASSWORD_ERROR	PDF 密码错误或缺失。
190003	PDF_FORMAT_ERROR	PDF 格式无效或文件损坏。
190004	PDF_SECURITY_ERROR	PDF 使用了不支持的加密方式。
190005	OCR_FAILURE	OCR 处理失败。
190006	JOB_TIMEOUT	处理超时。
190009	SDK_FILE_ERROR	文件无法打开或不存在。
190999	UPSTREAM_ERROR	未知处理引擎错误。