Error Handling Policy (Version 4)

This document defines canonical error-handling behavior for V4 document-person relationship expansion.

V4 keeps V3 transcription error behavior and adds policy/conflict handling for role extensibility, suggestion lifecycle transitions, and exclusivity enforcement.

Error Handling Objectives

Provide clear, actionable conflict and validation feedback for relationship write operations.
Prevent partial, silent, or destructive relationship mutations when policy checks fail.
Preserve suggestion review auditability with deterministic accept/reject outcomes.
Keep consistent API/UI/service error envelopes across relationship workflows.

Scope and Authority

Governs relationship-related error behavior in:

NiceGUI document/person relationship views,
FastAPI relationship and suggestion endpoints,
domain services for relationship sync and suggestion review,
persistence constraints for role, state, and exclusivity invariants.

Relationship Error Taxonomy

Category	Definition	Retriable
`validation_error`	Payload shape/type invalid, unknown role/state, malformed IDs	no
`not_found_error`	Target `Document`, `Person`, role, or suggestion record does not exist	no
`conflict_error`	Write violates uniqueness or exclusivity policy	no
`suggestion_state_error`	Invalid suggestion transition (for example accept after reject)	no
`policy_violation_error`	Action blocked by configured role matrix or governance rule	no
`infrastructure_transient_error`	Temporary DB or network instability during relationship operation	yes
`infrastructure_persistent_error`	Persistent DB/configuration failure	no
`internal_unexpected_error`	Unhandled exception/logic defect	no

Deterministic Conflict Behavior

When relationship writes fail policy checks:

Reject the full write operation (no partial apply).
Return structured conflict details including conflicting role pair and target identifiers.
Preserve existing canonical relationships unchanged.

When suggestion transitions fail:

Reject invalid state transition.
Return current state and allowed next actions.
Preserve suggestion record integrity.

API Error Response Contract

Relationship endpoints return a structured envelope:

^^^json { "error_id": "err_uuid_12345", "category": "conflict_error", "message": "Role assignment violates exclusivity policy.", "suggestion": "Remove recipient role before assigning author for this person on this document.", "details": { "document_id": "...", "person_id": "...", "attempted_role": "author", "conflicting_role": "recipient", "policy_rule": "author+recipient exclusive" }, "timestamp": "2026-08-09T15:00:00Z" } ^^^

HTTP status mappings:

validation_error -> 400
not_found_error -> 404
conflict_error, suggestion_state_error, policy_violation_error -> 409
infrastructure_transient_error -> 503
infrastructure_persistent_error, internal_unexpected_error -> 500

UI Error Presentation Rules

Display concise conflict summary with actionable next step.
Keep user edits in context (do not discard form state when feasible).
Differentiate between validation issues, policy conflicts, and infrastructure failures.
For bulk role sync operations, show per-item conflict context when multiple failures occur.

Logging and Audit Expectations

Log relationship write failures with correlation IDs.
Log suggestion acceptance/rejection outcomes with actor and timestamp where available.
Log policy matrix violations with deterministic machine-readable context.

Relationship-Specific Retry Guidance

Do not auto-retry policy or conflict failures.
Permit user-driven retry only after input changes.
Retry infrastructure transient failures with bounded policy in service layer if operation is idempotent.

4.1 KiB Raw Blame History