generated from john/python-template
98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
---
|
|
description: Cross-cutting error handling rules for services, API, and UI.
|
|
applyTo: 'src/transcription/**/*.py'
|
|
---
|
|
|
|
# Error Handling (Cross-cutting)
|
|
|
|
Primary references:
|
|
|
|
- `docs/ver4/error_handling_v4.md`
|
|
- `docs/invariant/error_handling.md`
|
|
- `docs/ver4/requirements_v4.md`
|
|
|
|
## Taxonomy and Categories
|
|
|
|
Use category-driven semantics aligned to canonical V4 policy:
|
|
|
|
- `validation`
|
|
- `not_found`
|
|
- `conflict`
|
|
- `external`
|
|
- `timeout`
|
|
- `internal`
|
|
|
|
Do not invent ad hoc categories in user/API-facing envelopes unless canonical docs are updated.
|
|
|
|
Runtime/internal categories may be more specific for diagnostics and persistence, but they must map
|
|
deterministically to the canonical envelope categories through the centralized mapper in
|
|
`transcription.errors.canonical_error_category`.
|
|
|
|
Current internal categories:
|
|
|
|
- `validation_error`
|
|
- `user_input_error`
|
|
- `not_found_error`
|
|
- `conflict_error`
|
|
- `external_provider_error`
|
|
- `external_timeout_error`
|
|
- `processing_error`
|
|
- `infrastructure_transient_error`
|
|
- `infrastructure_persistent_error`
|
|
- `internal_unexpected_error`
|
|
|
|
Required internal -> canonical mapping:
|
|
|
|
- `validation_error`, `user_input_error` -> `validation`
|
|
- `not_found_error` -> `not_found`
|
|
- `conflict_error` -> `conflict`
|
|
- `external_provider_error` -> `external`
|
|
- `external_timeout_error`, `infrastructure_transient_error` -> `timeout`
|
|
- `processing_error`, `infrastructure_persistent_error`, `internal_unexpected_error` -> `internal`
|
|
|
|
## Translation Boundaries
|
|
|
|
- **Provider/adapters:** raise provider/domain exceptions; do not emit UI text.
|
|
- **Services:** map raw exceptions into internal categories and preserve causal chain (`raise ... from ...`).
|
|
- **UI/API:** map internal category -> canonical envelope category and emit user-safe, actionable messages.
|
|
|
|
## Retry Rules
|
|
|
|
- No auto-retry for `validation`, `not_found`, `conflict`.
|
|
- `external`/`timeout` may be retried when operation semantics are safe.
|
|
- Preserve each retry as new evidence where applicable (no history rewrite).
|
|
|
|
## Job/Page Failure Semantics
|
|
|
|
- Page-level (`JobSource`): `pending`, `transcribed`, `failed`, `cancelled`.
|
|
- Job terminals: `transcribed`, `partial_success`, `failed`.
|
|
- Cancellation must keep job-level and page-level semantics explicit and consistent.
|
|
- Do not emit legacy terminal state language such as `completed` in active user/API lifecycle contracts.
|
|
|
|
## User-Safe Messaging
|
|
|
|
- Never leak stack traces, credentials, auth headers, or local filesystem paths in user-facing output.
|
|
- Include actionable remediation guidance aligned to category.
|
|
- Keep envelope structure consistent across API endpoints.
|
|
|
|
## Logging and Diagnostics
|
|
|
|
- Log operation identifiers and error IDs where available.
|
|
- Preserve category + cause-chain context.
|
|
- Distinguish no-response timeout/network failures from returned provider error responses.
|
|
|
|
## Guardrails
|
|
|
|
- No broad catch-and-swallow patterns.
|
|
- No success-shaped fallback values after exceptions.
|
|
- Category mapping must remain deterministic and testable.
|
|
|
|
## Contract Sync Rule
|
|
|
|
If taxonomy, retries, or envelope semantics change:
|
|
|
|
1. Update canonical docs (`docs/ver4/error_handling_v4.md`, and invariant docs if needed).
|
|
2. Update tests in the same change.
|
|
3. Update related instruction/skill references.
|
|
4. If change affects persisted status/category fields, update `docs/ver4/schema_v4.md` when applicable.
|