Error Handling

When using the PDFBOLT API, you may encounter various HTTP status codes indicating the outcomes of your requests. Understanding these codes can help you determine whether your request was successful or if there are issues that need to be addressed.

HTTP Status Codes

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

HTTP Status Code	errorCode	Meaning	Recommended Action
200	null	The request has succeeded, and the server has returned the requested data.	No action required. You can proceed to use the returned data as intended.
400	BAD_REQUEST	The server could not understand the request due to invalid syntax.	Check the errorMessage in the response. Fix the issue accordingly based on the provided message.
400	UNEXPECTED_ERROR	An unexpected error occurred during conversion.	Verify your request for correctness. Refer to the documentation for guidance or contact us at contact@pdfbolt.com.
400	URL_NOT_RESOLVED	Could not resolve the server name.	Verify the URL provided in the request.
400	HTTP_RESPONSE_FAILURE	Received an unexpected HTTP status code from the server.	Verify that the requested URL or resource is correct and accessible. Check the correctness of your authentication credentials, such as username and password, if required.
400	INVALID_CREDENTIALS	Authentication credentials provided are invalid or missing.	Verify the username and password provided in the request.
400	CUSTOM_S3_UPLOAD_ERROR	Failed to upload the document to your custom S3 bucket.	Check the errorMessage for detailed information about the issue. Regenerate a new pre-signed URL if needed. Ensure the pre-signed URL has not expired. Consider setting a longer expiration time for future uploads.
400	TARGET_CLOSED	The target page became unavailable or was closed.	Verify the URL provided in the request. Ensure the page remains accessible during the conversion process.
400	NO_BROWSER_CONTEXT	Failed to establish a connection with the browser.	Check your source and retry the request. If the issue persists, contact us at contact@pdfbolt.com.
400	PDF_PRINTING_FAILED	Failed to print 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.
401	UNAUTHORIZED	Authentication is required and has failed or has not been provided.	Verify that the API key is correct. Ensure that the API_KEY header is included in your request.
403	FORBIDDEN	You do not have permission to access the requested resource or action.	Refer to the details provided in the errorMessage for guidance. Ensure your API key has the required permissions for this resource or action.
404	NOT_FOUND	The requested resource could not be found on the server.	Verify the endpoint URL for typos. Refer to the API Endpoints for the correct URLs.
413	PAYLOAD_TOO_LARGE	The request entity is larger than the server is able to process.	Reduce the size of your request payload to meet the allowed limits. The maximum request size is 10MB for verified accounts and 1MB for unverified accounts.
413	PDF_SIZE_TOO_LARGE	The generated PDF size exceeds the maximum allowed size.	Reduce the size or complexity of the content to generate a smaller PDF. The maximum allowed size is 10MB for verified accounts and 2MB for unverified accounts.
429	TOO_MANY_REQUESTS	You have exceeded the allowed number of requests per minute or concurrent requests.	Refer to the Rate Limits section for more information. If your account is unverified, see the Unverified Accounts Limitations section for specific restrictions.
500	INTERNAL_SERVER_ERROR	The server encountered an unexpected condition that prevented it from fulfilling the request.	Retry the request later. If the issue persists, contact us with details of the request.
503	SERVICE_UNAVAILABLE	The server is currently unable to handle the request due to temporary overload or maintenance.	Wait a few moments and retry the request. Check the service Status Page for any ongoing maintenance.
504	CONVERSION_TIMEOUT	Conversion process timed out.	Check parameters such as waitForFunction, waitForSelector, and timeout in your request. Adjust them if necessary to prevent timeouts.

Error Response Format

In the event of an error, the API will return a JSON-formatted response containing details about the issue.

The structure of the error response is as follows:

{
  "timestamp": "2024-12-31T14:14:31Z",
  "httpErrorCode": 400,
  "errorCode": "INVALID_CREDENTIALS",
  "errorMessage": "Authentication credentials provided are invalid or missing. Please check username and password, or contact us at contact@pdfbolt.com."
}

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	Refer to errorCode values in the HTTP Status Codes table for all possible values.
errorMessage	string	A descriptive message explaining the error.

tip

• Use the information provided in the errorMessage field to understand what went wrong and how to correct it.
• If you are unable to resolve the issue, consider reaching out to the support team with the error details for further assistance.