transcription/.github/instructions/error-handling.instructions.md

description, applyTo

description	applyTo
Cross-cutting error handling rules for services, API, and UI.	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.