The upload screen says processing failed, and the user has no idea whether to retry, enter a password or scan the document again. A generic error transfers the diagnostic work to someone without access to the pipeline.
For teams building ingestion products, report failures at the level where the user can act. Preserve technical evidence for support without putting internal stack traces into the main workflow.
What makes an ingestion error actionable?
It identifies the affected document or page, explains the current usable state and provides an appropriate next step. The message should distinguish a temporary processing failure from a source-quality or access problem.
Do not label the whole document failed when only one page needs review, unless that is the product's intentional acceptance boundary. Equally, do not call the document complete while an important page remains unprocessed.
Map failure classes to recovery
Use fictional files to verify the proposed report. The actual error categories should match observable pipeline states.
| Failure class | Useful user action |
|---|---|
| Password needed | Use the approved secure access flow |
| Unsupported format | Choose a supported file or conversion path |
| Poor scan quality | Replace or review the affected page |
| Temporary dependency failure | Retry under a bounded policy |
| Partial extraction | Inspect incomplete sections and their limits |
| Access no longer valid | Contact the appropriate document owner |
A retry button should target recoverable work without duplicating existing search entries or losing approved corrections. Some errors require a changed input rather than another identical attempt.
Keep support evidence separate from the message
Retain a correlation reference, processing stage and appropriately limited diagnostic detail. Avoid logging document passwords, private page text or unrestricted file links merely to make support easier.
The protected PDF guide covers access-state handling. The page manifest guide helps explain partial completion accurately.
Test whether the user can recover without coaching
Ask a reviewer to resolve a fictional bad scan or failed page from the report alone. Inspect whether the next action preserves the original, updates the correct version and produces an understandable final state.
My knowledge platform contribution supplies related project context, not a claim that this report design exists in every integration. A new workflow needs its own user and support review.
Record known limits honestly. If the product cannot distinguish two failure causes, explain the combined condition and appropriate support path rather than inventing a precise diagnosis that may send the user in the wrong direction.
Should users see the full technical error?
Provide task-relevant explanation and a support reference, with sensitive diagnostics available only through appropriate access.
Should every failure offer an immediate retry?
Only when retry is meaningful and controlled. A missing password or unreadable source needs a different action.
What should we test first?
Fail one page and ask a reviewer to recover it using the report during the ingestion workflow discussion.