transcription/docs/error_handling.md

Error Handling

This document defines the canonical error-handling policy for the document transcription system. It is the single source of truth for how errors are classified, surfaced to users, logged for diagnosis, and handled across UI, API, service, worker, and provider boundaries.

Error Handling Objectives

The production error-handling model is designed to:

• make failures visible to the user in clear, actionable language
• preserve enough diagnostic detail for fast troubleshooting
• keep module behavior consistent across all boundaries
• distinguish expected domain failures from unexpected defects
• support safe retries for transient failures without hiding persistent faults

Scope And Authority

This page governs error-handling behavior for:

• UI interactions (NiceGUI pages)
• API endpoints (FastAPI routes)
• application services and orchestration logic
• in-process background worker execution
• external provider adapters and persistence adapters

If implementation behavior conflicts with this document, this document is authoritative and implementation should be updated.

Core Principles

• Clarity first: user-facing messages should explain what failed in plain language.
• Actionability required: each surfaced error should include a suggested next step.
• Safety by default: internal details are logged; sensitive details are not exposed by default in UI/API.
• Consistency across boundaries: category and structure should remain stable from source to surface.
• Fail explicitly: silent failure is prohibited.
• Traceability: every non-trivial error should be traceable with an error reference ID.

Error Taxonomy

The system uses stable, implementation-independent categories:

Category	Definition	Typical Source	Retriable
validation_error	Payload or parameter shape/content is invalid	UI/API input validation, service guards	no
user_input_error	User-provided artifact is unacceptable though structurally valid	unsupported file type, empty file, oversized upload	sometimes
not_found_error	Requested resource does not exist	missing job/document/transcript	no
conflict_error	Requested operation violates current state constraints	invalid state transition	no
external_provider_error	External AI/provider call fails	upstream HTTP/API/provider failures	sometimes
infrastructure_transient_error	Temporary environment issue	network timeout, DB connection reset	yes
infrastructure_persistent_error	Non-transient environment issue	missing permissions, misconfiguration	no
internal_unexpected_error	Unhandled defect or unknown failure	uncaught exceptions, logic errors	unknown (default no)

Classification Rules

• Classification occurs as close as possible to the origin boundary.
• Provider-specific exceptions must be normalized into taxonomy categories before crossing service boundaries.
• Unknown exceptions are classified as internal_unexpected_error and logged with traceback.
• Category names are stable contracts and must not be changed casually.

User-Facing Error Experience Contract

When an error is shown in the GUI, it must include:

1. Title (short context, e.g., “Upload failed”)
2. Message (plain-language explanation)
3. Suggested action (explicit next step)
4. Error reference ID (for support/debug traceability)
5. Technical details (optional/collapsible for advanced users)

UI Message Rules

• Do not expose raw stack traces by default.
• Do not expose secrets, credentials, connection strings, or filesystem internals unless explicitly in debug tooling.
• Prefer domain language over implementation language.
• Use persistent visibility for important failures (dialog/card), not only transient toasts.

Suggested Action Requirements

Every user-visible error must include a suggested course of action, such as:

• retry the operation
• check file type/size constraints
• refresh the jobs page
• verify environment configuration
• contact operator with error ID and timestamp

API Error Response Contract

API errors should return a structured envelope with stable fields:

• error_id: short unique reference ID
• category: taxonomy category
• message: safe human-readable summary
• suggestion: recommended next step
• details: optional, only when safe and appropriate
• timestamp: UTC ISO-8601

HTTP status mapping guidance:

• validation_error, user_input_error -> 400
• not_found_error -> 404
• conflict_error -> 409
• external_provider_error -> 502 or 503 (depending on failure mode)
• infrastructure_transient_error -> 503
• infrastructure_persistent_error -> 500
• internal_unexpected_error -> 500

Logging And Observability Contract

All logged errors must include, where available:

• error_id
• category
• operation (e.g., upload.submit, worker.process_job, jobs.refresh)
• exception_type
• job_id, document_id (when relevant)
• UTC timestamp

Rules:

• Use structured logging fields where practical.
• Use full traceback for unexpected errors (internal_unexpected_error).
• Log at boundary handoff points to preserve causal trail.
• Avoid duplicate noisy logging for the same exception at every layer.

Recovery And Retry Policy

Retriable Conditions

Retriable failures include:

• transient network/provider timeouts
• intermittent provider unavailability
• temporary DB/network interruptions

Non-Retriable Conditions

Non-retriable failures include:

• invalid file formats
• missing required data
• permission/configuration failures
• deterministic domain conflicts

Worker Behavior

• The worker must classify and persist failure details consistently.
• Retries should be bounded by configured limits.
• Exhausted retries must end in explicit failed status with recorded reason.
• No infinite retry loops are allowed.

Boundary-Specific Responsibilities

UI Layer

Responsibility:

• display user-safe error summaries and suggested actions
• show persistent error visibility for critical failures
• include error reference IDs in visible output

Out of scope:

• low-level exception parsing
• provider-specific protocol interpretation

API Layer

Responsibility:

• map application exceptions into stable error envelopes and HTTP statuses
• preserve category and error_id continuity

Out of scope:

• domain-specific remediation logic

Service Layer

Responsibility:

• classify domain and infrastructure exceptions
• convert adapter-specific failures into taxonomy categories
• return deterministic error types to callers

Out of scope:

• presentation formatting for UI

Worker Layer

Responsibility:

• execute retry policy for retriable failures
• persist terminal failure details for jobs
• emit operational logs with category and identifiers

Out of scope:

• direct UI messaging

Provider Adapter Layer

Responsibility:

• normalize provider SDK/HTTP failures into domain-neutral exceptions
• preserve raw provider context for logs (safely)

Out of scope:

• choosing user-facing wording

Error Lifecycle Workflow

Standard lifecycle:

1. Failure occurs at a boundary or operation.
2. Exception is classified into taxonomy category.
3. error_id is created (or propagated).
4. Error is logged with required structured fields.
5. User/API receives safe message + suggested action.
6. Persistent job/resource state is updated when applicable.
7. Tests verify contract behavior for the pathway.

Test Strategy For Error Handling

Unit Tests

• category classification behavior
• retry eligibility decisions
• exception-to-message mapping safety

Integration Tests

• UI pathways show clear message + suggested action for known failures
• API returns structured error envelope with expected status/category
• worker persists failed status and failure detail as required

Regression Tests

• each previously observed production issue should have a guarding test
• contract tests must cover adapter error normalization behavior

Known Failure Patterns And Prescribed Responses

Pattern	Category	User Message	Suggested Action
Upload payload cannot be parsed by UI handler	internal_unexpected_error (until narrowed)	Upload failed due to unexpected processing error	Retry once; if repeated, report error ID and check runtime version compatibility
Unsupported extension	user_input_error	File type is not supported	Upload JPG, PNG, TIFF, or PDF
Empty file upload	validation_error	Uploaded file is empty	Choose a valid non-empty file and retry
Provider timeout	external_provider_error or infrastructure_transient_error	Transcription provider timed out	Retry from jobs page; if repeated, check provider status
Job lookup missing	not_found_error	Requested job was not found	Refresh jobs list and open a valid job

Governance And Update Process

This document is a living policy artifact.

Update this document when:

• new error categories are introduced
• handling behavior changes at any boundary
• a production incident reveals missing guidance
• API/UI error contracts change

Change requirements:

• update this document and associated tests in the same change set
• preserve taxonomy stability; if changed, document migration impact
• record noteworthy policy changes in project release notes or changelog

Related Pages

• System overview
• Architecture
• Requirements
• Intent

Glossary

• Error category: Stable classification used to drive handling, messaging, and status mapping.
• Error envelope: Structured API payload describing a failure.
• Error reference ID: Short identifier used to correlate user-visible failure with logs.
• Retriable error: Failure likely to succeed on a later attempt without code changes.
• Terminal failure: Failure state after retries are exhausted or retry is not allowed.