Error Handling Policy (Version 4)

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

Error Handling Objectives

Make failures visible in clear, actionable language at both the document and page levels.
Support isolated failure handling in multi-page jobs so one failing page does not invalidate successful pages.
Preserve diagnostic detail for validation failures, provider failures, and policy conflicts.
Ensure consistent error envelope structure across API, UI, service, and worker boundaries.

Scope and Authority

This policy governs error behavior across:

NiceGUI pages
FastAPI routes
Service-layer orchestration
asyncio worker tasks
Database interactions
Provider adapters

Error Taxonomy

Category	Definition	Retriable
`validation_error`	Payload, parameter, or schema validation failure	no
`user_input_error`	Unacceptable file, invalid selection, or malformed request from the operator	no
`not_found_error`	Requested `Document`, `Source`, `Person`, `Job`, role, or type does not exist	no
`conflict_error`	Operation violates uniqueness or relationship-write policy	no
`external_provider_error`	Provider API failure, rate limit, or execution problem	yes
`infrastructure_transient_error`	Temporary DB, file-system, or network instability	yes
`infrastructure_persistent_error`	Persistent configuration, credential, or database availability failure	no
`internal_unexpected_error`	Uncaught exception or logic defect	no

Async Batch and Page-Level Error Behavior

In multi-page asyncio processing:

Exceptions from individual page calls are trapped within the page task wrapper.
Failed page detail is written to JobSource.error_detail and the page state becomes failed.
Aggregate job status is derived from page outcomes:
- all pages succeed -> completed
- some succeed and some fail -> partial_success
- all fail -> failed
Successful pages remain valid even when sister pages fail.

Relationship and Classification Conflict Behavior

When relationship or document-type writes fail policy checks:

Reject the full write operation.
Return structured conflict detail including target identifiers and the violated rule.
Preserve existing persisted relationships unchanged.

API Error Response Contract

API error responses return a structured envelope:

^^^json { "error_id": "err_uuid_12345", "category": "conflict_error", "message": "Relationship write conflicts with existing links.", "suggestion": "Adjust the requested relationship links and retry.", "details": { "document_id": "...", "person_id": "...", "attempted_role": "recipient", "operation": "add_link", "conflict_reason": "duplicate document-person-role link" }, "timestamp": "2026-08-10T15:00:00Z" } ^^^

HTTP status mappings:

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

UI Error Presentation Rules

Display concise failure summaries with the next action the operator can take.
Keep form state in context when feasible.
Distinguish validation issues, conflict issues, provider failures, and infrastructure failures.
For bulk relationship updates, identify the specific role or person that caused a conflict.

Logging and Audit Expectations

Log worker failures with correlation IDs and provider context.
Log relationship and classification conflicts with machine-readable detail.
Log persisted provider errors and page-level execution failures.

Retry Guidance

Do not auto-retry validation or conflict failures.
Permit user-driven retry after the input or selection changes.
Allow bounded retry for transient provider or infrastructure failures when the operation is idempotent.

4.1 KiB Raw Blame History