Error Codes

Error Response Format

Conversion service error responses use the following JSON structure:

json

{
  "code": 100104,
  "errorCode": "FILE_TOO_LARGE",
  "message": "Human-readable description",
  "traceId": "a1b2c3d4e5f6..."
}

Field	Type	Description
`code`	Integer	Numeric error code, programmatic identifier
`errorCode`	String	Semantic error identifier, for readability only
`message`	String	Error description
`traceId`	String	Full-link trace ID

Common Service Error Codes

These errors are handled by the service framework and apply to all ComPDF API endpoints.

01xxx — System Errors

Code	HTTP	Description
`01001`	500	Internal system error
`01002`	500	Failed to upload processed file to storage
`01003`	500	File upload error
`01004`	500	Failed to download your uploaded file
`01005`	400	File cannot be empty
`01006`	400	Invalid parameters, please set valid file parameters
`01007`	400	Task ID cannot be empty

02xxx — File Format Errors

Code	HTTP	Description
`02001`	400	File format error
`02002`	400	Unsupported file format for processing
`02003`	400	Unsupported image format
`02201`	400	The file is encrypted
`02207`	400	Failed to open file: unsupported format or encrypted
`02209`	413	File too large, please upload a smaller file
`02210`	500	File processing failed
`02212`	500	File processing failed: abnormal output file size

03000 — Parameter Validation Error

Code	HTTP	Description
`03000`	400	Parameter validation failed, typically due to missing required fields or incorrect field formats

04xxx — File & Business Errors

Code	HTTP	Description
`04001`	400	File key does not exist
`04002`	400	File size is zero
`04003`	400	File does not exist or cannot be opened
`04007`	400	Only one file is allowed for this endpoint
`04008`	400	Merge PDF supports at most 5 files

05xxx — Task Errors

Code	HTTP	Description
`05001`	404	Task does not exist or is invalid
`05002`	409	Abnormal task status
`05003`	400	File count per task has reached the threshold
`05004`	410	Task expired and was not executed
`05005`	400	At least one file is required per task

06001 — Insufficient Assets

Code	HTTP	Description
`06001`	402	You have run out of processing quota, please purchase a plan

Authentication & Authorization

HTTP	Code	Description
`401`	`401`	Invalid or missing API Key; authentication service unavailable
`403`	`403`	Insufficient permissions

Conversion Functional Error Codes

These errors originate from the document conversion service.

100xxx — General Request & File Errors

Code	Error Code	HTTP	Description
`100001`	`INVALID_REQUEST`	400	Missing or malformed parameters
`100101`	`INVALID_FILE_TYPE`	415	Uploaded file is not a PDF
`100104`	`FILE_TOO_LARGE`	413	File exceeds sync limit, use async endpoint
`100105`	`PAGE_LIMIT_EXCEEDED`	422	PDF page count exceeds limit

120xxx — Authentication Errors

Code	Error Code	HTTP	Description
`120001`	`AUTH_REQUIRED`	401	Missing authentication credentials
`120002`	`INVALID_TOKEN`	403	Invalid or expired authentication token

130xxx — Business State Errors

Code	Error Code	HTTP	Description
`130001`	`NOT_FOUND`	404/410	Document or job not found, or result has been cleaned
`130002`	`JOB_NOT_READY`	409	Job not yet completed, cannot download
`130003`	`INVALID_STATE`	409	Job already in terminal state, cannot cancel
`130004`	`IDEMPOTENCY_IN_PROGRESS`	409	Request with same idempotency key is being processed

190xxx — Processing & System Errors

Code	Error Code	HTTP	Description
`190001`	`CONVERT_FAILED`	500	Document conversion failed (corrupted file or internal error)
`190002`	`PDF_PASSWORD_ERROR`	422	Incorrect or missing PDF password
`190003`	`PDF_FORMAT_ERROR`	400	Invalid PDF format or corrupted file
`190004`	`PDF_SECURITY_ERROR`	400	PDF uses unsupported encryption
`190005`	`OCR_FAILURE`	500	OCR recognition failed
`190006`	`JOB_TIMEOUT`	408	Conversion processing timed out
`190007`	`NO_TABLE`	422	No tables found in source file
`190008`	`OUT_OF_MEMORY`	500	Out of memory during processing, try a smaller file
`190009`	`FILE_ERROR`	400	File cannot be opened or does not exist
`190010`	`IMAGE_INVALID`	400	Invalid, corrupted, or unsupported image format
`190999`	`INTERNAL_ERROR`	500/503	Internal service error or dependency not ready

Retry Recommendations

Error Code Range	Retryable	Recommendation
`100xxx`	No	Fix request parameters or file and resubmit
`120xxx`	No	Fix authentication credentials and resubmit
`130001`–`130004`	Depends	Resource-not-found not retryable; state conflict can retry after checking
`190001`–`190010`	Recommended	Service processing issues, backoff and retry (max 3 times)
`190999`	Recommended	Internal error, backoff and retry
`06001`	No	Purchase a plan to continue
`01xxx`, `02xxx`, `04xxx`	No	Fix the file or parameters and retry

Error Codes ​

Error Response Format ​

Common Service Error Codes ​

01xxx — System Errors ​

02xxx — File Format Errors ​

03000 — Parameter Validation Error ​

04xxx — File & Business Errors ​

05xxx — Task Errors ​

06001 — Insufficient Assets ​

Authentication & Authorization ​

Conversion Functional Error Codes ​

100xxx — General Request & File Errors ​

120xxx — Authentication Errors ​

130xxx — Business State Errors ​

190xxx — Processing & System Errors ​

Retry Recommendations ​