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.

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.