Skip to main content
There are two distinct ways a Draftable API operation can go wrong, and a robust integration needs to handle both. The second one catches people out. A comparison that accepts cleanly can still fail minutes later.

​
Request failures

These are returned by the API straight away.

​
Common causes of 400

  • file_type missing. It is required on both sides and is never inferred from the file name.
  • Both file and source_url supplied for one side. Provide exactly one.
  • Neither supplied for one side. Each side needs a document.
  • A duplicate identifier. Identifiers must be unique within your account.
  • The file exceeds your account limits. By default around 40 MB and 1,000 pages per file.

​
Common causes of 404

  • The identifier is wrong, or has a typo.
  • The comparison was created with your other credential set. A comparison created with test credentials is invisible to production credentials, and the reverse.
  • The comparison has been deleted, or its expiry_time has passed.

​
Processing failures

A comparison is accepted, processed, and finishes unsuccessfully. It will show:
Always check failed after ready becomes true. Treating ready: true as success is the single most common integration bug, and it presents to your users as a viewer that will not load.
error_message describes what went wrong. Typical causes:

​
Diagnosing a source_url failure

This is the most frequent processing failure, and it is almost always an access problem rather than a Draftable problem.
1

Confirm the URL is publicly reachable

Fetch it from a machine outside your network, with no VPN and no session cookies. A URL that works from your office may be invisible to Draftable.
2

Check it needs no authentication

Draftable sends no credentials when fetching a source_url. Pages behind a login return a login page rather than the document.
3

Check it returns the file directly

The URL must return the document itself, not an HTML page containing a download link, and not a redirect to a consent screen.
4

If in doubt, upload the file instead

Uploading with file removes the fetch entirely and rules the whole class of problem out. For documents on an internal network, this is the only option.

​
Building a resilient integration

1

Check both ready and failed

Never present a viewer URL without confirming ready is true and failed is false.
2

Set an overall timeout

Decide how long you are prepared to wait, and surface a clear message to the user after that, rather than polling indefinitely.
3

Log the error message

Store error_message against your own record of the comparison. It is what support will ask for.
4

Back off when polling

Increase the interval between checks rather than polling at a fixed short interval.
5

Retry request failures selectively

Retrying a 400 or a 401 will not help, because the request itself is wrong. Transient network errors are worth retrying.

​
Checking whether the problem is Draftable

If comparisons are failing broadly rather than for specific documents, check the service status before investigating your own integration. See Checking Draftable API status.

​
Getting help

Contact support@draftable.com with:
  • The comparison identifier
  • The error_message returned
  • Roughly when it was created
  • Whether it used test or production credentials
  • The documents involved, if you are able to share them
The identifier is the most useful single item, because it lets us look up exactly what happened.

Creating a comparison

Authenticating with the Draftable API

Checking Draftable API status