generated from john/python-template
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
# Error Handling Policy (Version 4)
|
|
|
|
This policy defines active V4 error taxonomy, translation boundaries, and retry semantics.
|
|
|
|
## Error Categories
|
|
|
|
| Category | Meaning | Typical Origin | User Treatment |
|
|
| :--- | :--- | :--- | :--- |
|
|
| `validation` | Input payload/selection is invalid | UI form parsing, service validators | Inline correction guidance |
|
|
| `not_found` | Target record is missing | ID lookup in service layer | Non-blocking warning or redirect |
|
|
| `conflict` | State prevents requested action | lifecycle transitions, duplicate semantic keys | Explain required precondition |
|
|
| `external` | Provider/network dependency failure | OpenRouter/provider adapter | Retry path and evidence retained |
|
|
| `timeout` | Provider call exceeded configured bound | worker/provider client timeout | Retry path and bounded messaging |
|
|
| `internal` | Unexpected local failure | unhandled service/runtime faults | Safe generic message + diagnostics capture |
|
|
|
|
## Translation Boundaries
|
|
|
|
- **Provider layer:** raise provider-scoped exceptions with provider context; do not emit UI text.
|
|
- **Service layer:** map raw exceptions into domain-aware categories and preserve causal chain.
|
|
- **UI/API layer:** convert category to user-safe message with contextual action guidance.
|
|
|
|
## Job and Page Failure Semantics
|
|
|
|
### Page-Level (`JobSource`)
|
|
|
|
- `pending` -> `transcribed` when attempt succeeds.
|
|
- `pending` -> `failed` when attempt fails terminally.
|
|
- `pending` -> `cancelled` on job cancellation before processing.
|
|
|
|
### Job-Level (`Job`)
|
|
|
|
- `transcribed` when all pages transcribe successfully.
|
|
- `partial_success` when mixed success/failure outcomes exist.
|
|
- `failed` when no page transcribes successfully.
|
|
|
|
## Retry and Retranscription Rules
|
|
|
|
1. Failed/cancelled pages may be re-queued through retranscription workflows.
|
|
2. Retry attempts must append new `ExecutionAttempt` rows; prior evidence remains immutable.
|
|
3. Selecting a better candidate must update projection pointers, not mutate historical attempt rows.
|
|
|
|
## Logging and Diagnostics Rules
|
|
|
|
1. Persist sufficient attempt error metadata (`error_category`, `error_message`, transport evidence) for post-hoc analysis.
|
|
2. Avoid leaking stack traces or local paths into user-facing message envelopes.
|
|
3. Preserve causal exception chains for internal diagnostics.
|
|
|
|
## UI Messaging Contract
|
|
|
|
- User-visible errors must be actionable, bounded, and category-consistent.
|
|
- Multi-page jobs must show partial outcomes instead of collapsing into a single opaque failure.
|
|
- Recovery actions (`retry`, `retranscribe`, `edit input`) must be offered where available.
|
|
|
|
## Cross-Reference
|
|
|
|
- [Error Handling invariant](../invariant/error_handling.md)
|
|
- [System Requirements](requirements_v4.md)
|
|
- [Data Model](schema_v4.md)
|