# 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/error_handling.md).

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

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

## Relationship and Classification Conflict Behavior

When relationship or document-type writes fail policy checks:

1. Reject the full write operation.
2. Return structured conflict detail including target identifiers and the violated rule.
3. 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.

## Related Local References

- [Error Handling Invariant](../invariant/error_handling.md)
- [System Overview](index_v4.md)
- [System Requirements](requirements_v4.md)
- [Data Model](schema_v4.md)
- [System Architecture](architecture_v4.md)