generated from john/python-template
89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
# Error Handling Policy (Version 2)
|
|
|
|
This document defines the canonical error-handling policy for the V2 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 responses) in PostgreSQL `JSONB` 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, PostgreSQL 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 caught within the `asyncio` task wrapper.
|
|
2. **Page Record Logging:** Page failure detail is 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-07-31T07:55: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)
|
|
- [PostgreSQL documentation](https://www.postgresql.org/docs/)
|
|
- [Python asyncio](https://docs.python.org/3/library/asyncio.html#module-asyncio)
|
|
- [Pydantic Validation](https://pydantic.dev/docs/validation/latest/get-started/)
|
|
- [Pydantic AI](https://pydantic.dev/docs/ai/overview/)
|
|
|
|
## Related Local References
|
|
|
|
- [System Overview](index_v2.md)
|
|
- [System Design Intent](intent.md)
|
|
- [Transcription Methodology](transcription_methodology.md)
|
|
- [System Architecture](architecture_v2.md)
|
|
- [System Requirements](requirements_v2.md)
|
|
- [Data model](schema_v2.md)
|
|
- Error Handling Policy (this document)
|
|
- [Implementation Plan](implementation_plan_v2.md)
|