Troubleshooting

Error Codes

PDFKong uses conventional HTTP response codes to indicate the success or failure of an API request. Every error response is returned in a predictable, unified JSON format to make programmatic error handling straightforward.

Unified Response Format

Regardless of the HTTP status code, every error generated by our API will follow the exact same JSON structure, featuring a unique request_id and a specific error.code.

application/json

{
  "request_id": "b6d4b4a1-8d2a-4b9d-b8e7-1d8f7e6a5c3b",
  "success": false,
  "billed": false,
  "error": {
    "code": "HD-A...",
    "message": "Human-readable explanation of the error.",
    "details": null // Contains validation object on HD-A001
  }
}

Application Error Codes

HTTP 422 HD-A001

Validation Error

The provided parameters failed schema validation. This happens when required fields are missing, or values are of the wrong data type. The error.details field will contain an object detailing exactly which parameters failed and why.

HTTP 402 HD-A002

Payment Required (Insufficient Credits)

Your account does not have enough prepaid or free credits to complete the requested conversion. Please visit your dashboard to top up your wallet balance.

HTTP 401 HD-A003

Unauthorized

The API token provided in the Authorization: Bearer header is missing, invalid, or has been revoked.

HTTP 404 HD-A004

Task Not Found

The requested resource (e.g., a PDF Task ID for deletion) could not be found. It may have already been deleted, expired, or you do not have permission to access it.

HTTP 409 HD-A005

Idempotency Conflict

A request with the same Idempotency-Key is already currently processing. Please wait for the initial request to complete rather than dispatching parallel requests with identical keys.

HTTP 408 HD-A408

Request Timeout

The PDF generation took longer than the maximum allowed timeout window for your request type. This typically happens with extremely large web pages or complex office documents. Your credits are not billed for timed-out requests.

HTTP 500 HD-A000

Internal Server Error

A generic, unexpected error occurred on our servers while attempting to process your request. This is automatically logged to our monitoring systems for immediate investigation.