Errors

Error envelope

Every non-2xx response has the same body. code is drawn from a closed vocabulary and is what your code should branch on; message is human-readable and may change.

{
  "error": {
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "original must be a .docx, .doc, or .pdf file",
    "request_id": "01J..."
  }
}

Send an X-Request-Id header to correlate your logs with ours. If you don't, one is minted and echoed back in the response.

Request errors

The *_NOT_FOUND codes intentionally cover both "doesn't exist" and "not yours", so ids cannot be probed for existence.

INTERNAL_ERROR is the only code worth retrying blindly. A response that carries Retry-After tells you when to try again: TRIAL_RATE_LIMITED, ELEMENT_MAP_PENDING, and CONFLICT for work still being made. Everything else in this table describes a request or account condition that will produce the same result next time. The trial codes are explained under API trials.

Comparison failures

A comparison that cannot be generated is not an HTTP error. The request succeeded — it correctly reported that the work will not finish — so it returns 200 with "status": "failed":

{
  "comparison_id": "cmp_...",
  "status": "failed",
  "error": {
    "code": "DOCUMENT_PROTECTED",
    "upstream_code": "ONE_OR_MORE_DOCUMENTS_ARE_PROTECTED"
  }
}

failed is terminal for that comparison. Waiting longer changes nothing; submit a new comparison to retry.

A comparison whose redline succeeded but one of whose renderings did not (a PDF, say) also reports failed, but with no error: what was produced is in file.downloads, and the missing formats are named in file.failed_formats. A merge whose records can no longer produce a document reports MERGE_UNUSABLE. Edits and created documents fail the same way, with EDIT_FAILED and CREATION_FAILED; an amend whose change collides with a later version reports CARRY_CONFLICT. The live text for every code is also served by GET /v1/reference/errors.

DOCUMENT_UNREADABLE appears in both tables because a .docx is checked for readability while the request is still open — an unopenable one is refused with 400 rather than accepted and failed later. A .doc or .pdf source is opaque until its conversion step, so the same condition surfaces there as a failed status instead.

Pipeline failure codes

upstream_code comes from the document pipeline and is more specific than the public codes above. The ones you are most likely to see:

OUT_OF_MEMORY on very large or deeply nested documents is worth reporting to support — it is usually a fixable characteristic of the specific file rather than a hard limit.