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/error_handling.md
• docs/invariant/error_handling.md
• docs/requirements.md

Taxonomy and Categories

Use category-driven semantics aligned to canonical 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.

AppError.message vs AppError.detail

AppError carries two texts with different audiences, and they must not be collapsed. Getting this wrong has already caused a real defect in this repository, in both directions.

Attribute	Audience	Reaches	Rule
message	User and API clients	ErrorEnvelope.message, UI notifications	Stays generic. Never embed exception text, provider payloads, or filesystem paths.
detail	Internal only	Logs, and format_error_detail -> ExecutionAttempt.error_detail and MaintenanceRun.error_detail	Carries the root cause. Never rendered to users or serialized into an envelope.

• Putting root-cause data in message leaks infrastructure detail to users.
• Omitting it from detail silently degrades the provenance record this system exists to preserve — a failed attempt whose error_detail says nothing is an attempt that cannot be diagnosed later.
• When you raise from a caught exception, populate both: a generic message and a detail carrying type(exc).__name__ and the exception text, with raise ... from exc.
• detail is optional (None). A read path that assumes it is populated must handle its absence.
• Before changing either attribute, or any helper that formats them, enumerate every consumer — evidence writes, maintenance runs, logging, API envelopes, and UI presentation all read these fields, and tests assert on the persisted text.

Canonical definitions live in src/transcription/errors.py; see also docs/error_handling.md.

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/error_handling.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/schema.md when applicable.