Definition of Error Codes

When a request fails, ComPDF Self-hosted returns one normalized error response. Conversion and PDF processing errors use HTTP 200 and preserve the relevant business error in the JSON body. Errors produced by ComPDF Self-hosted itself retain the corresponding 4xx or 5xx HTTP status.

The type field identifies the error-code namespace. Always use type together with code or errorCode: the conversion engine and PDF SDK reuse some numeric codes with different meanings. A conversion SDK error can use its original SDK numeric code, such as 4, while API and server errors normally use six-digit business codes.

json

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

Fields

Field	Type	Description
`type`	String	Error source: `conversion`, `pdf`, or `server`.
`code`	Number	Numeric code returned by the source. Conversion SDK errors can use the original SDK code; API and server errors normally use six-digit business codes.
`errorCode`	String	Stable semantic error identifier corresponding to `code`.
`message`	String	English human-readable error description. For documented processing errors, this follows the corresponding SDK error definition.
`traceId`	String	Trace identifier for correlating the request with service logs.

Error Sources and Duplicate Codes

`type`	Source	`errorCode` behavior
`conversion`	Conversion processing	Identifies a conversion-processing error.
`pdf`	PDF processing	Identifies a PDF-processing error.
`server`	ComPDF Self-hosted	The error is generated by ComPDF Self-hosted and uses the Server error-code definition.

The same numeric value can mean different things for different sources. For example, 120001 is AUTH_REQUIRED for type: "conversion", but PASSWORD_REQUIRED for type: "pdf". Likewise, 190005 is OCR_FAILURE for conversion and RESOURCE_EXHAUSTED for PDF processing.

ComPDF Web uses type and errorCode to display localized error text. API clients should also use these stable fields for programmatic handling and should not parse message.

Common Error Codes

HTTP Status	`code`	`errorCode`	Meaning
`200`	Processing code	Processing `errorCode`	A conversion or PDF-processing business error occurred. `type` identifies whether it is `conversion` or `pdf`.
`400`	`100001`	`BAD_REQUEST` / `VALIDATION_ERROR`	Missing or invalid server request parameters.
`401`	`140001`	`UNAUTHORIZED`	Missing or invalid `x-api-key` or admin session.
`403`	`140002`	`FORBIDDEN` / `INVALID_TOKEN`	The request is not permitted.
`404`	`150001`	`NOT_FOUND`	Resource or task was not found.
`409`	`150002` / `150003`	`TASK_NOT_READY` / `CONFLICT` / `INVALID_STATE`	Task or resource state does not allow the request.
`413`	`100104`	`FILE_TOO_LARGE`	Uploaded file exceeds the ComPDF Self-hosted request limit before processing.
`429`	`130012`	`CONCURRENCY_LIMIT`	Too many requests reached ComPDF Self-hosted concurrently.
`500`	`190999`	`INTERNAL_ERROR`	Unexpected server error.

Request Example

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

Processing Engine Business Codes

All processing errors in this table are returned with HTTP 200. The conversion catalog includes original numeric codes such as 4 (PDF_PAGE_ERROR) and six-digit conversion API codes. Refer to the source-specific type before interpreting overlapping values.

`code`	`errorCode`	Meaning
`100001`	`INVALID_REQUEST` (`conversion`) / `INVALID_ARGUMENT` (`pdf`)	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`	`AUTH_REQUIRED` (`conversion`) / `PASSWORD_REQUIRED` (`pdf`)	Authentication is required for conversion; a password is required for PDF processing.
`120002`	`INVALID_TOKEN` (`conversion`) / `INVALID_PASSWORD` (`pdf`)	Token is invalid for conversion; password is invalid for PDF processing.
`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` (`conversion`) / `SDK_PROCESS_FAILED` (`pdf`)	Conversion or SDK processing failed.
`190002`	`PDF_PASSWORD_ERROR` (`conversion`) / `TEMP_FILE_WRITE_FAILED` (`pdf`)	Password failure for conversion; temporary-file write failure for PDF processing.
`190003`	`PDF_FORMAT_ERROR` (`conversion`) / `TEMP_FILE_READ_FAILED` (`pdf`)	PDF format failure for conversion; temporary-file read failure for PDF processing.
`190004`	`PDF_SECURITY_ERROR` (`conversion`) / `RESULT_PACKAGE_FAILED` (`pdf`)	PDF security failure for conversion; result packaging failure for PDF processing.
`190005`	`OCR_FAILURE` (`conversion`) / `RESOURCE_EXHAUSTED` (`pdf`)	OCR failure for conversion; insufficient resources for PDF processing.
`190006`	`JOB_TIMEOUT` (`conversion`) / `REQUEST_TIMEOUT` (`pdf`)	Conversion task timeout or PDF processing request timeout.
`190009`	`SDK_FILE_ERROR`	File cannot be opened or found.
`190999`	`UPSTREAM_ERROR`	Unknown processing engine error.

Definition of Error Codes ​

Fields ​

Error Sources and Duplicate Codes ​

Common Error Codes ​