Error Handling

Preconditions: A compare or align request has been started, and the host application is listening for terminal viewer events.

• 1Treat the documented Revision completion and error outcomes as terminal states for the active workflow request.
• 2On every terminal event, clear loading indicators, unlock blocked controls, and stop request timers.
• 3Capture the technical error details for developer diagnostics, but show the user a short recovery-oriented message.
• 4Classify the error by likely cause: access, unsupported file, invalid option, alignment quality, timeout, or unexpected viewer failure.
• 5Offer one next action instead of a generic failure: retry, replace file, refresh authorization, reduce DPI, run alignment, or contact support with diagnostics.
• 6Never leave the UI in a permanent processing state after a failed compare, failed align, or cancelled alignment.

Use this matrix as application guidance. Exact emitted payload details should be read from the Revision API reference and runtime event payloads.

• Access or fetch failure: Confirm the URL is reachable by the viewer runtime, refresh expired authorization, or route the file through an approved proxy. Tell the user the file could not be loaded and ask them to refresh access or choose another file.
• Unsupported or corrupt file: Block unsupported extensions before submit where possible, and ask the user to provide a supported, healthy source file.
• Invalid compare option: Bind DPI and color choices to validated controls, reset invalid values to a supported option, and let the user retry manually.
• Poor alignment result: Ask the operator to retry with clearer reference points that are far apart and visible in both revisions.
• Timeout or large document failure: Clear the active state, suggest a lower DPI or simpler source, and allow manual retry.
• Unexpected viewer failure: Log the diagnostic payload, release the UI, preserve the user inputs, and show a fallback message with a retry option.

Every failure path leaves the application usable. The user sees what failed, the UI is unlocked, valid inputs are preserved, and the next recovery action is clear.

Do not auto-retry destructive or expensive operations without user intent. For Revision workflows, prefer manual retry after changing the failed condition, because repeated compare requests can be slow and may hide the real setup issue.