Error Handling Policy (Version 4)

This document defines the Version 4 taxonomy, contracts, and framework behavior used to satisfy the cross-version Error Handling invariant.

Invariant Alignment

Version 4 implements the invariant through:

The shared error taxonomy below.
Structured error envelopes with correlation IDs.
Page-level failure isolation and explicit aggregate job status.
Atomic relationship and classification writes.
Consistent translation across API, UI, service, worker, persistence, and provider boundaries.
Bounded retry guidance based on category and idempotency.

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.3 KiB Raw Blame History