Error Handling

This page covers non-2xx application errors returned by the PDFBolt API.

Successful responses are documented on each endpoint page:

• /v1/direct – immediate PDF response.
• /v1/sync – URL-based access.
• /v1/async – background processing with webhook.
• /v1/usage – account usage and quota.

Service Status

For ongoing platform issues or scheduled maintenance, check the PDFBolt Status Page.

HTTP Status Codes

Below is a table of common HTTP status codes, their meanings, and recommended actions:

HTTP Status Code	errorCode	Meaning	Recommended Action
400	BAD_REQUEST	The request cannot be processed due to invalid format or parameter values.	Read the errorMessage field – it usually names the invalid field. Fix the request and retry.
400	UNEXPECTED_ERROR	An unexpected error occurred during conversion.	Read the errorMessage field for details. Verify your request parameters. If the issue persists, contact us at contact@pdfbolt.com.
400	URL_NOT_RESOLVED	Could not resolve the URL's domain name.	Verify the URL provided in the request.
400	HTTP_RESPONSE_FAILURE	The target page returned a non-2xx status code (e.g., 404, 500).	Verify that the requested URL or resource is correct and accessible. Verify your authentication credentials, such as username and password, if required.
400	INVALID_CREDENTIALS	The httpCredentials (username/password) supplied for the target page were rejected or missing. Not related to your PDFBolt API key.	Verify the httpCredentials for the page you are converting. For PDFBolt API key errors, see 401 UNAUTHORIZED.
400	CUSTOM_S3_UPLOAD_ERROR	Failed to upload the document to your custom S3 bucket.	Check the errorMessage for the specific cause (expired URL, bucket permissions, or network issue). If the URL has expired, regenerate the pre-signed URL with a longer expiration time.
400	TARGET_CLOSED	The target page became unavailable or was closed.	Verify the URL provided in the request. Ensure the page stays available during conversion.
400	NO_BROWSER_CONTEXT	The internal browser engine failed to start or process the request.	Retry the request. If the issue persists, contact us at contact@pdfbolt.com.
400	PDF_PRINTING_FAILED	Failed to render the PDF. The file may be too large or complex.	Reduce the size or complexity of the PDF. Optimize images and other elements to simplify the document.
400	TEMPLATE_EVAL_ERROR	Failed to evaluate the template. The Handlebars syntax in your template could not be processed with the provided templateData.	Check the errorMessage for the specific syntax issue. Verify your template's Handlebars syntax (variables, conditionals). Ensure templateData field names match your template variables.
401	UNAUTHORIZED	Authentication is required but failed or was not provided.	Verify that the API key is correct. Ensure that the API-KEY header is included in your request.
403	FORBIDDEN	The API key is valid, but the account cannot perform this action. Common causes: exhausted document conversions, async conversions not available on the current plan.	Read the errorMessage field for the specific cause. Check your plan and remaining conversions in the Dashboard. Upgrade your plan if you need async conversions or more credits.
404	NOT_FOUND	The requested API endpoint could not be found on the server.	Verify the endpoint URL for typos. Refer to the API Endpoints for the correct URLs.
408	CONVERSION_TIMEOUT	Conversion process timed out.	Check parameters such as waitForFunction, waitForSelector, and timeout in your request. Adjust them if necessary to prevent timeouts.
413	PAYLOAD_TOO_LARGE	The request payload exceeds the allowed size.	Reduce the size of your request payload to meet the allowed limits. Free plan: 1MB max request size. Paid plans: 10MB.
413	PDF_SIZE_TOO_LARGE	The generated PDF size exceeds the maximum allowed size. Free plan limit: 2MB per PDF. No size limit on paid plans.	Use compression to reduce PDF size. Free plan: keep generated PDFs under 2MB. Paid plans: no size limit – each 5MB of generated PDF is charged as 1 document. x-pdfbolt-conversion-cost response header reports the charged document count (0 for failed conversions).
422	UNPROCESSABLE_ENTITY	Your request could not be processed. May indicate an unsupported edge case or an internal issue.	Retry once if the request is valid. If the same error persists, contact us at contact@pdfbolt.com with the timestamp, endpoint, and errorMessage.
429	TOO_MANY_REQUESTS	You have exceeded the allowed minute, hour, day, or concurrent request limits.	Back off and retry later using exponential backoff. See Rate Limits for plan limits.
5XX	SERVICE_UNAVAILABLE / GATEWAY_TIMEOUT	Server-side error. Infrastructure-level errors may not include the standard JSON error format.	Retry with exponential backoff. Check the Status Page for ongoing incidents or maintenance. If the issue persists, contact us at contact@pdfbolt.com with the details.

Error Response Format

Application-level errors use the JSON format below. Infrastructure errors (network, gateway, CDN, maintenance) may return a different body or no body at all – treat any HTTP 5XX response as a transient failure and retry it, even without an errorCode.

Error responses have the following structure:

{
  "timestamp": "2026-05-04T14:29:09Z",
  "httpErrorCode": 401,
  "errorCode": "UNAUTHORIZED",
  "errorMessage": "The API key is missing, invalid or has been blocked. Please verify your key or contact support."
}

Error Response Fields

Property Name	Type	Description
timestamp	string	The date and time when the error occurred, in ISO 8601 format (UTC).
httpErrorCode	number	The HTTP status code of the error.
errorCode	string	See the HTTP Status Codes table for all possible errorCode values.
errorMessage	string	A descriptive message explaining the error.

Async Conversion Failures

Validation, authentication, and rate-limit errors for /v1/async are returned immediately as HTTP errors using the JSON format above.

Failures that happen after the request is accepted (e.g., timeout, target unreachable) are delivered to your webhook with status: "FAILURE" and an errorCode. The webhook payload differs from the immediate HTTP error – it does not include the numeric httpErrorCode (HTTP status) or timestamp.

Example webhook failure payload:

{
  "requestId": "a5a87a23-07b4-4bd6-8194-c150d6045c60",
  "status": "FAILURE",
  "errorCode": "URL_NOT_RESOLVED",
  "errorMessage": "Could not resolve the server name. Please verify the URL.",
  "documentUrl": null,
  "expiresAt": null,
  "isAsync": true,
  "duration": 550,
  "documentSizeMb": null,
  "isCustomS3Bucket": false
}

See retryDelays for retry behavior.

Retry Guidance

Use this table to decide whether to retry a failed request and which backoff strategy to apply:

Status	Retryable	Strategy
400	Usually no	Fix the request and retry – check errorMessage for the cause. For transient codes (NO_BROWSER_CONTEXT, TARGET_CLOSED, UNEXPECTED_ERROR), retry once before fixing the request.
401	No	Verify the API-KEY header.
403	No	Check plan, credits, or feature availability.
408	Sometimes	Adjust timeout/waitUntil/waitForFunction, or switch to /v1/async.
413	No	Reduce request or PDF size, or upgrade plan.
429	Yes, after delay	Use exponential backoff – PDFBolt does not return a Retry-After header.
5XX	Yes	Treat as transient server-side failure. Use exponential backoff with jitter.

Troubleshooting

• Read the errorMessage first – it returns specific details about what went wrong.
• If you are unable to resolve the issue, contact us via the contact form, email at contact@pdfbolt.com, or live chat – include the timestamp, endpoint, HTTP status, and errorCode. Do not include API keys, passwords, cookies, or sensitive request data.