Definition of Error Codes

When a JSON request fails, ComPDF Self-hosted returns a normalized error response. If the PDF SDK or conversion processing engine returns a numeric business code, the service preserves it as bizCode and returns the corresponding semantic errorCode when available.

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

Fields

Field	Type	Description
code	String	HTTP status code as a string.
msg	String	Human-readable error message.
data	Null	Always null for errors.
errorCode	String	Local or processing-engine semantic error code.
bizCode	Number	Processing-engine numeric business code, when available.
traceId	String	Trace identifier, when available.
details	Any	Validation details or extra diagnostic data.

Common Error Codes

HTTP Status	errorCode	Meaning
400	BAD_REQUEST / VALIDATION_ERROR / INVALID_REQUEST / INVALID_ARGUMENT	Missing or invalid request parameters.
401	UNAUTHORIZED	Missing or invalid x-api-key or admin session.
403	FORBIDDEN / INVALID_TOKEN	Authenticated request is not allowed or upstream token is invalid.
404	NOT_FOUND	Resource or task was not found.
409	TASK_NOT_READY / INVALID_STATE	Task is not ready or is already in a terminal state.
413	FILE_TOO_LARGE	Uploaded file exceeds the allowed size.
429	CONCURRENCY_EXCEEDED / CONCURRENCY_LIMIT	Too many concurrent requests.
500	INTERNAL_ERROR	Unexpected server error.
502	UPSTREAM_ERROR	File processing service returned an error or timed out.

Request Example

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

Processing Engine Business Codes

bizCode	errorCode	Meaning
100001	INVALID_REQUEST / INVALID_ARGUMENT	Invalid request or argument.
100002	INVALID_JSON	Invalid JSON in request or options.
100101	INVALID_FILE_TYPE	Uploaded file type is not supported.
100102	FILE_REQUIRED	Required file field is missing.
100103	FILE_COUNT_MISMATCH	File count does not match parameters.
100104	FILE_TOO_LARGE	Uploaded file is too large.
100105	PAGE_LIMIT_EXCEEDED	Page limit exceeded.
100106	INVALID_OUTPUT_FILE_NAME	Output file name is invalid.
110001	INVALID_PAGE_RANGE	Page range is invalid.
110002	INVALID_PAGE_INDEX	Page index is invalid.
110003	INVALID_RECT	Rectangle parameter is invalid.
110004	INVALID_QUAD_RECTS	Quad rectangle parameter is invalid.
110005	PAGE_RANGE_EMPTY	Page range resolves to no pages.
120001	PASSWORD_REQUIRED	Password is required.
120002	INVALID_PASSWORD	Password is invalid.
120201	ICC_PROFILE_REQUIRED	ICC profile file is required.
120202	ICC_PROFILE_INVALID	ICC profile file is invalid.
130003	INVALID_STATE	Task state does not allow this action.
190001	CONVERT_FAILED / SDK_PROCESS_FAILED	Conversion or SDK processing failed.
190002	PDF_PASSWORD_ERROR	PDF password is incorrect or missing.
190003	PDF_FORMAT_ERROR	PDF format is invalid or damaged.
190004	PDF_SECURITY_ERROR	PDF encryption is not supported.
190005	OCR_FAILURE	OCR processing failed.
190006	JOB_TIMEOUT	Processing timed out.
190009	SDK_FILE_ERROR	File cannot be opened or found.
190999	UPSTREAM_ERROR	Unknown processing engine error.