generated from john/python-template
88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# Error Handling Policy (Version 3)
|
|
|
|
This document defines the canonical error-handling policy for the v3 document transcription system.
|
|
|
|
## Error Handling Objectives
|
|
|
|
* Make failures visible in clear, actionable language at both the document and individual page levels.
|
|
* Support **isolated failure handling** in multi-image batches so single page errors do not crash an entire batch job.
|
|
* Preserve diagnostic detail (Pydantic validation errors, raw provider REST envelopes, exact input prompts) in generic database JSON structures for fast troubleshooting.
|
|
* Ensure consistent error envelope structure across API, UI, and async worker boundaries.
|
|
|
|
## Scope And Authority
|
|
|
|
Governs error behavior across NiceGUI pages, FastAPI routes, service orchestration, `asyncio` background tasks, database interactions, and AI provider adapters.
|
|
|
|
## Error Taxonomy
|
|
|
|
| Category | Definition | Retriable |
|
|
| --- | --- | --- |
|
|
| `validation_error` | Pydantic payload or parameter schema validation failure | no |
|
|
| `user_input_error` | Unacceptable user file (unsupported image type, corrupt file) | no |
|
|
| `not_found_error` | Requested resource (`Document`, `Source`, `Person`, `Job`) missing | no |
|
|
| `conflict_error` | Operation violates state constraints (e.g., duplicate `document_person` role) | no |
|
|
| `external_provider_error` | AI Provider API failure (rate limit, vision execution error) | yes |
|
|
| `infrastructure_transient_error` | Temporary DB connection reset or HTTP timeout | yes |
|
|
| `infrastructure_persistent_error` | Database down, missing API credentials, misconfiguration | no |
|
|
| `internal_unexpected_error` | Uncaught Python exception or logic defect | no |
|
|
|
|
## Async Batch & Page-Level Error Behavior
|
|
|
|
In multi-image `asyncio` batch processing:
|
|
|
|
1. **Page Isolation:** Exceptions caught during individual page calls are trapped within the `asyncio` task wrapper.
|
|
2. **Page Record Logging:** Page failure details, along with the prompt inputs and hyperparameters attempted, are written directly to `job_source.error_detail` and `job_source.status = 'failed'`.
|
|
3. **Batch Aggregate State:**
|
|
* If **all** page tasks succeed -> `job.status = 'completed'`.
|
|
* If **some** page tasks fail -> `job.status = 'partial_success'`.
|
|
* If **all** page tasks fail -> `job.status = 'failed'`.
|
|
|
|
|
|
4. **Retry Strategy:** The UI exposes a "Retry Failed Pages" option for `partial_success` jobs, which spawns a new targeted `Job` containing *only* the `Source` IDs marked as `failed`.
|
|
|
|
## API Error Response Contract
|
|
|
|
API error responses return a structured JSON envelope:
|
|
^^^json
|
|
{
|
|
"error_id": "err_uuid_12345",
|
|
"category": "validation_error",
|
|
"message": "The uploaded payload failed schema validation.",
|
|
"suggestion": "Check file format and metadata fields, then try again.",
|
|
"details": {
|
|
"pydantic_errors": [...]
|
|
},
|
|
"timestamp": "2026-08-08T15:00:00Z"
|
|
}
|
|
^^^
|
|
|
|
HTTP Status Mappings:
|
|
|
|
* `validation_error`, `user_input_error` -> `400`
|
|
* `not_found_error` -> `404`
|
|
* `conflict_error` -> `409`
|
|
* `external_provider_error` -> `502` / `503`
|
|
* `infrastructure_transient_error` -> `503`
|
|
* `infrastructure_persistent_error`, `internal_unexpected_error` -> `500`
|
|
|
|
---
|
|
|
|
## Technology References
|
|
|
|
* [FastAPI documentation](https://fastapi.tiangolo.com/)
|
|
* [NiceGUI documentation](https://nicegui.io/documentation)
|
|
* [SQLModel documentation](https://sqlmodel.tiangolo.com/)
|
|
* [Python asyncio](https://www.google.com/search?q=https://docs.python.org/3/library/asyncio.html%23module-asyncio)
|
|
* [Pydantic Validation](https://pydantic.dev/docs/validation/latest/get-started/)
|
|
|
|
## Related Local References
|
|
|
|
- [System Overview](index_v3.md)
|
|
- [System Design Intent](invariant/intent.md)
|
|
- [Transcription Methodology](invariant/transcription_methodology.md)
|
|
- [System Architecture](architecture_v3.md)
|
|
- [System Requirements](requirements_v3.md)
|
|
- [Data model](schema_v3.md)
|
|
- Error Handling Policy (this document)
|
|
- [Implementation Plan](implementation_plan_v3.md)
|