> ## 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](/hc/en-us/articles/Draftable-API-authentication) |
| **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.
</Warning>

`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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Building a resilient integration

<Steps>
  <Step title="Check both ready and failed">
    Never present a viewer URL without confirming `ready` is `true` and `failed` is `false`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Log the error message">
    Store `error_message` against your own record of the comparison. It is what support will ask for.
  </Step>

  <Step title="Back off when polling">
    Increase the interval between checks rather than polling at a fixed short interval.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/hc/en-us/articles/43677873463705-Checking-Draftable-API-Status).

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

<CardGroup>
  <Card title="Creating a comparison" icon="file-import" href="/hc/en-us/articles/Draftable-API-creating-a-comparison" iconType="solid" horizontal />

  <Card title="Authenticating with the Draftable API" icon="key" href="/hc/en-us/articles/Draftable-API-authentication" iconType="solid" horizontal />

  <Card title="Checking Draftable API status" icon="signal" href="/hc/en-us/articles/43677873463705-Checking-Draftable-API-Status" iconType="solid" horizontal />
</CardGroup>