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