generated from john/python-template
111 lines
4.1 KiB
Markdown
111 lines
4.1 KiB
Markdown
# 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 exclusivity 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": "Role assignment violates exclusivity policy.",
|
|
"suggestion": "Remove recipient 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-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
|
|
|
|
- [System Overview](index_v4.md)
|
|
- [System Requirements](requirements_v4.md)
|
|
- [Data Model](schema_v4.md)
|
|
- [System Architecture](architecture_v4.md)
|