> ## Documentation Index
> Fetch the complete documentation index at: https://help.draftable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling errors and comparison failures

> The two kinds of failure in the Draftable API, the HTTP status codes you should handle, and how to diagnose a comparison that finished unsuccessfully.

There are two distinct ways a Draftable API operation can go wrong, and a robust integration needs to handle both.

| Kind of failure | When it happens | How you detect it |
| :- | :- | :- |
| **Request failure** | Immediately | A non-2xx HTTP status code |
| **Processing failure** | Later, during comparison | `failed: true` on an otherwise ready comparison |

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.

| Status | Meaning | What to do |
| :- | :- | :- |
| **400 Bad Request** | The request was malformed | Check required parameters. Most often a missing `file_type`, or supplying both `file` and `source_url` on the same side |
| **401 Unauthorized** | Authentication failed | Check the `Authorization: Token ...` header. See [Authenticating with the Draftable API](https://help.draftable.com/hc/en-us/articles/Draftable-API-authentication.md) |
| **404 Not Found** | The comparison or export does not exist | Check the identifier. Remember comparisons are only visible to the credential set that created them |

### 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:

```json theme={null}
{
  "identifier": "aBcDeFgH",
  "ready": true,
  "failed": true,
  "error_message": "..."
}
```

> [!WARNING]
>
> 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:

| Cause | Explanation |
| :- | :- |
| **A `source_url` could not be fetched** | The URL was unreachable from the public internet, required authentication, returned an error, or timed out |
| **The file was not the declared type** | A file submitted as `docx` that is actually something else |
| **The file is corrupt or unreadable** | Draftable could not parse the document |
| **The file is password protected** | Encrypted documents cannot be compared. Remove protection before submitting |
| **The file exceeds size or page limits** | Detected during processing rather than at submission |

## 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](https://help.draftable.com/hc/en-us/articles/43677873463705-Checking-Draftable-API-Status.md).

## Getting help

Contact **[support@draftable.com](mailto: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.

## Related articles

> [card] [Creating a comparison](https://help.draftable.com/hc/en-us/articles/Draftable-API-creating-a-comparison.md)

> [card] [Authenticating with the Draftable API](https://help.draftable.com/hc/en-us/articles/Draftable-API-authentication.md)

> [card] [Checking Draftable API status](https://help.draftable.com/hc/en-us/articles/43677873463705-Checking-Draftable-API-Status.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.