generated from john/python-template
73 lines
2.5 KiB
Markdown
73 lines
2.5 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.
|
|
Service-layer exceptions must normalize to this category set before crossing service boundaries.
|
|
|
|
## Translation Boundaries
|
|
|
|
- **Provider/adapters:** raise provider/domain exceptions; do not emit UI text.
|
|
- **Services:** map raw exceptions into domain categories and preserve causal chain (`raise ... from ...`).
|
|
- **UI/API:** emit user-safe, actionable messages based on category + operation context.
|
|
|
|
## 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.
|