DocRaptor API requests are synchronous by default, with a hard time limit of 60 seconds. This is the best option for most documents, but if you have very large or complex documents, you may wish to switch to asynchronous document creation. Async requests have an extended time limit of 600 seconds.
Most DocRaptor users use one of our programming language specific libraries. which include example code for setting up asynchronous document creation. For the nitty-gritty details of making asynchronous documents with our REST APi, continue reading!
Async Doc Creation
Async documents are created using the same API endpoint as standard requests. To make them async, simply set async to true .
Unlike synchronous requests, async requests will not return a document. Instead, the response is a JSON object with a status_id , e.g.
{
"status_id": "123454321"
}To get the document, you can either poll the status URL or set a callback_url on your initial request. When the document has been rendered successfully, DocRaptor will call the specified callback_url via a POST request. Note: If there is an error creating your document, the callback_url will never be called. The status page will explain the error.
Getting Async Doc Status
Poll the async status API to get an async document's status:
https://docraptor.com/status/{status_id}Some things to note:
These request must be authenticated.
status_idis the value returned by the initial async document creation request.
Status API Responses
Responses from the status API will always be a JSON object. Here's an example response:
{
"download_url": "https://docraptor.com/download/12345asdf",
"message": "Completed at Mon Jun 06 18:33:17 +0000 2011",
"number_of_pages": 2,
"status": "completed"
}The status API response will always have a key of status . Depending on the value of that key, the response may include other keys as well. The possible values for status are:
queued
This means the document has been queued but processing has not yet begun.working
This means the document is currently being processed.completed
This means your document has completed rendering.failed
This means DocRaptor encountered an error generating the document.
If the document has a status of completed , look for the key download_url in the response JSON. The value associated with that key is a URL from which you can download your doc. This download URL can be used to download your document up to 100 times, and will expire after your account's data retention period. For accounts with the "as short as possible" data retention setting, documents can only be downloaded once.
If the document has a status of failed , the status response will also have the key validation_errors with a value corresponding to the reason for the failure. An example of this is:
{
"status": "failed",
"validation_errors": "Name can't be blank\nName is too long (maximum is 200 characters)"
}There will only ever be a single string value for validation_errors, but multiple errors may be included. The response includes newlines (\n ) to separate the reasons. Here are the possible errors:
Document type can't be blank
Document type is not included in the list
Name is too long (maximum is 200 characters)
Over document limit. Please upgrade your account.
Tag is too long (maximum is 200 characters)
Document creation failed due to unknown reasons.
Account canceled. Please update payment details or contact DocRaptor support.
Account suspended. Please update payment details (reactivation may take a few minutes)