Errors

REST error envelope

Every non-2xx REST 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

COMPARISON_NOT_FOUND and MERGE_NOT_FOUND 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. Everything else in this table describes a request or account condition that will produce the same result next time.

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.

MCP errors

The MCP server does not use HTTP status codes for tool outcomes. Failures surface two ways.

Tool errors — a call that cannot proceed raises an MCP tool error carrying a message. These are argument and permission problems: too few revisions for a merge, a project the signed-in user cannot access, an exhausted upload allowance. Read the message; it says what is wrong.

Statuses — a call that succeeded but whose artifact isn't ready reports it in the result:

A comparison can be partly successful: some formats generate while others fail. Such a comparison carries both downloads and failed_options with a failure_code. Anything present in the manifest is valid and usable.

Transfer errors

The upload endpoint returns ordinary HTTP status codes:

A 403 most often means the upload manifest is more than an hour old. Call the create tool again with the same version_story_id to stage fresh transfers.

If a transfer fails with a host-allowlist error rather than a status code, the calling agent's network policy is blocking *.versionstory.com. For Claude, the fix is in Settings → Capabilities — the illustrated steps are in Claude Connector Setup.

Pipeline failure codes

failure_code and upstream_code come from the document pipeline and are 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.