transcription/docs/error_handling_v2.md

Error Handling Policy (Version 2)

This document defines the canonical error-handling policy for the V2 document transcription system.

Error Handling Objectives

• Make failures visible in clear, actionable language at both the document and individual page levels.
• Support isolated failure handling in multi-image batches so single page errors do not crash an entire batch job.
• Preserve diagnostic detail (Pydantic validation errors, raw provider responses) in PostgreSQL JSONB for fast troubleshooting.
• Ensure consistent error envelope structure across API, UI, and async worker boundaries.

Scope And Authority

Governs error behavior across NiceGUI pages, FastAPI routes, service orchestration, asyncio background tasks, PostgreSQL interactions, and AI provider adapters.

Error Taxonomy

Category	Definition	Retriable
validation_error	Pydantic payload or parameter schema validation failure	no
user_input_error	Unacceptable user file (unsupported image type, corrupt file)	no
not_found_error	Requested resource (Document, Source, Person, Job) missing	no
conflict_error	Operation violates state constraints (e.g., duplicate document_person role)	no
external_provider_error	AI Provider API failure (rate limit, vision execution error)	yes
infrastructure_transient_error	Temporary DB connection reset or HTTP timeout	yes
infrastructure_persistent_error	Database down, missing API credentials, misconfiguration	no
internal_unexpected_error	Uncaught Python exception or logic defect	no

Async Batch & Page-Level Error Behavior

In multi-image asyncio batch processing:

1. Page Isolation: Exceptions caught during individual page calls are caught within the asyncio task wrapper.
2. Page Record Logging: Page failure detail is written directly to job_source.error_detail and job_source.status = 'failed'.
3. Batch Aggregate State:

• If all page tasks succeed -> job.status = 'completed'.
• If some page tasks fail -> job.status = 'partial_success'.
• If all page tasks fail -> job.status = 'failed'.

4. Retry Strategy: The UI exposes a "Retry Failed Pages" option for partial_success jobs, which spawns a new targeted Job containing only the Source IDs marked as failed.

API Error Response Contract

API error responses return a structured JSON envelope:

{
"error_id": "err_uuid_12345",
"category": "validation_error",
"message": "The uploaded payload failed schema validation.",
"suggestion": "Check file format and metadata fields, then try again.",
"details": {
"pydantic_errors": [...]
},
"timestamp": "2026-07-31T07:55:00Z"
}

HTTP Status Mappings:

• validation_error, user_input_error -> 400
• not_found_error -> 404
• conflict_error -> 409
• external_provider_error -> 502 / 503
• infrastructure_transient_error -> 503
• infrastructure_persistent_error, internal_unexpected_error -> 500

---

Technology References

• FastAPI documentation
• NiceGUI documentation
• PostgreSQL documentation
• Python asyncio
• Pydantic Validation
• Pydantic AI

Related Local References

• System Overview
• System Design Intent
• Transcription Methodology
• System Architecture
• System Requirements
• Data model
• Error Handling Policy (this document)
• Implementation Plan