Error Handling

This page explains PDFBolt API error responses, async conversion failures, and retry guidance.

Successful responses are documented on each endpoint page:

• /v1/direct – immediate PDF response.
• /v1/sync – temporary download URL.
• /v1/async – background processing with webhook delivery.
• Template API – creating and managing reusable templates.
• /v1/usage – current plan and remaining conversions.

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 supplied for the target page were rejected or missing. This error does not refer 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	The custom S3 storage endpoint rejected the document upload.	Check the errorMessage for the specific cause, such as an expired URL, invalid signature, insufficient permissions, or missing required headers. 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	The browser could not render the PDF.	Reduce the size or complexity of the source content. Optimize images and other assets. Check the page dimensions and make sure the margins leave a printable content area.
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	PDFBolt could not authenticate the request because the required credential is missing or invalid.	For Conversion API requests, verify the API key and the API-KEY header. For protected Template API requests, verify the Personal Access Token and the PERSONAL-ACCESS-TOKEN header.
403	FORBIDDEN	The credential is valid, but the account cannot perform this action. Common causes include no remaining conversions, a feature unavailable on the current plan, or reaching the template limit.	Read the errorMessage field for the specific cause. Check your plan, remaining conversions, and templates in the Dashboard. Upgrade your plan if you need additional features, conversions, or templates.
404	NOT_FOUND	The requested endpoint or resource could not be found.	Verify the endpoint URL for typos and refer to the API Endpoints for the correct URL. For Template API requests, verify the template ID.
408	CONVERSION_TIMEOUT	The 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 or template data exceeds an applicable size limit.	Reduce the affected request or template field to meet the allowed limit. Conversion API: 1 MB on the Free plan and 10 MB on paid plans. Template API: separate per-field limits apply. See Request fields.
413	PDF_SIZE_TOO_LARGE	The generated PDF size exceeds the maximum allowed size. Free plan limit: 2 MB per PDF. No size limit on paid plans.	Use compression to reduce PDF size. Free plan: keep generated PDFs under 2 MB. Paid plans: no size limit. Each 5 MB of generated PDF is charged as 1 document.
422	UNPROCESSABLE_ENTITY	PDFBolt could not process the request because of 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	The applicable Conversion API or Template API request limit was exceeded.	For Conversion API and Template API rendering requests, use exponential backoff with jitter; these responses do not include Retry-After. For Template API management requests, wait for the Retry-After delay and add jitter before retrying. See Rate Limits for endpoint-specific limits.
499	CLIENT_DISCONNECTED	The client disconnected before PDFBolt could fully deliver the response.	Check your client, proxy, or gateway timeout settings. Keep the connection open until the response completes. For long‑running conversions, use /v1/async.
5xx	SERVICE_UNAVAILABLE / GATEWAY_TIMEOUT	A server-side or infrastructure error occurred. The response may use a different body or no body.	Retry the request 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 from a network, gateway, CDN, or maintenance event may return a different body or no body. 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	integer	The HTTP status code of the error.
errorCode	string	See the HTTP Status Codes table for common errorCode values.
errorMessage	string	A descriptive message explaining the error.

Async Conversion Failures

Authentication, request validation, and rate-limit errors detected before /v1/async accepts the request are returned immediately as HTTP errors using the JSON format above.

Failures that occur after the request is accepted, such as a timeout or target page error, are delivered to your webhook with status: "FAILURE" and an errorCode. The webhook payload differs from an immediate HTTP error and does not include httpErrorCode 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
}

Retry Guidance

Use this table for errors returned as immediate HTTP responses, including errors returned before an async request is accepted. For async conversions, retryDelays configures retry attempts before the final webhook is sent. If the webhook reports a final failure, use its errorCode to diagnose the problem.

Status	Retryable	Strategy
400	Usually no	Check errorMessage and correct the request before retrying. For transient codes (NO_BROWSER_CONTEXT, TARGET_CLOSED, UNEXPECTED_ERROR), retry once.
401	No	Verify API-KEY for the Conversion API or PERSONAL-ACCESS-TOKEN for protected Template API endpoints.
403	No	Check the plan, remaining conversions, template limit, or feature availability.
404	No	Correct the endpoint URL or template ID before retrying.
408	Sometimes	Adjust timeout, waitUntil, or other wait parameters.
413	No	Reduce the request or PDF size. Upgrade the plan only if errorMessage identifies a plan-specific PDF limit.
422	Sometimes	Retry once. If the same error persists, contact PDFBolt support.
429	Yes, after delay	Conversion and rendering endpoints: use exponential backoff with jitter. Template management endpoints: honor Retry-After, add jitter, and then retry.
499	Client-dependent	Do not retry automatically. Increase client, proxy, or gateway timeouts, or use /v1/async for long‑running conversions.
5xx	Yes	Treat it as a transient server-side failure. Retry with exponential backoff and jitter.

Troubleshooting

• Read the errorMessage first. It usually provides specific details about what went wrong.
• If you are unable to resolve the issue, use the contact form, email us at contact@pdfbolt.com, or contact us through live chat. Include the endpoint, HTTP status, errorCode, and timestamp when available. Do not include API keys, passwords, cookies, or sensitive request data.