# 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:

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

When suggestion transitions fail:

1. Reject invalid state transition.
2. Return current state and allowed next actions.
3. 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.

## Related Local References

- [V4 Scope Boundary](scope_boundary_v4.md)
- [V4 Requirements](requirements_v4.md)
- [V4 Schema](schema_v4.md)
- [V4 Architecture](architecture_v4.md)
- [V3 Error Handling](../error_handling_v3.md)