transcription/docs/ver4/error_handling_v4.md

Error Handling Policy (Version 4)

This policy defines active V4 error taxonomy, translation boundaries, and retry semantics.

Error Categories

Category	Meaning	Typical Origin	User Treatment
validation	Input payload/selection is invalid	UI form parsing, service validators	Inline correction guidance
not_found	Target record is missing	ID lookup in service layer	Non-blocking warning or redirect
conflict	State prevents requested action	lifecycle transitions, duplicate semantic keys	Explain required precondition
external	Provider/network dependency failure	OpenRouter/provider adapter	Retry path and evidence retained
timeout	Provider call exceeded configured bound	worker/provider client timeout	Retry path and bounded messaging
internal	Unexpected local failure	unhandled service/runtime faults	Safe generic message + diagnostics capture

Translation Boundaries

• Provider layer: raise provider-scoped exceptions with provider context; do not emit UI text.
• Service layer: map raw exceptions into domain-aware categories and preserve causal chain.
• UI/API layer: convert category to user-safe message with contextual action guidance.

Job and Page Failure Semantics

Page-Level (JobSource)

• pending -> transcribed when attempt succeeds.
• pending -> failed when attempt fails terminally.
• pending -> cancelled on job cancellation before processing.

Job-Level (Job)

• transcribed when all pages transcribe successfully.
• partial_success when mixed success/failure outcomes exist.
• failed when no page transcribes successfully.

Retry and Retranscription Rules

1. Failed/cancelled pages may be re-queued through retranscription workflows.
2. Retry attempts must append new ExecutionAttempt rows; prior evidence remains immutable.
3. Selecting a better candidate must update projection pointers, not mutate historical attempt rows.

Logging and Diagnostics Rules

1. Persist sufficient attempt error metadata (error_category, error_message, transport evidence) for post-hoc analysis.
2. Avoid leaking stack traces or local paths into user-facing message envelopes.
3. Preserve causal exception chains for internal diagnostics.

UI Messaging Contract

• User-visible errors must be actionable, bounded, and category-consistent.
• Multi-page jobs must show partial outcomes instead of collapsing into a single opaque failure.
• Recovery actions (retry, retranscribe, edit input) must be offered where available.

Cross-Reference

• Error Handling invariant
• System Requirements
• Data Model