Error handling added to MVP according to error_handling.md guideline

tests/services/test_transcription.py

@@ -60,9 +60,12 @@ class TestPromptLoading:
         prompt_dir.mkdir()
 
         settings = Settings(openrouter_api_key="test-key", prompt_dir=prompt_dir)
-        with pytest.raises(PromptLoadError):
+        with pytest.raises(PromptLoadError) as exc_info:
             load_prompt_text(settings=settings)
 
+        assert exc_info.value.category.value == "infrastructure_persistent_error"
+        assert "verify prompt_dir" in exc_info.value.suggestion.lower()
+
 
 @pytest.mark.unit
 class TestImageLoading:
@@ -83,9 +86,12 @@ class TestImageLoading:
         """Image loader raises TranscriptionError when image file does not exist."""
         missing = tmp_path / "missing.png"
 
-        with pytest.raises(TranscriptionError):
+        with pytest.raises(TranscriptionError) as exc_info:
             load_image_payload(missing)
 
+        assert exc_info.value.category.value == "not_found_error"
+        assert "verify" in exc_info.value.suggestion.lower()
+
 
 @pytest.mark.unit
 class TestTranscriptionService:
@@ -123,5 +129,9 @@ class TestTranscriptionService:
         settings = Settings(openrouter_api_key="test-key", prompt_dir=prompt_dir)
         provider = _FakeProvider(error=ProviderError("upstream failure"))
 
-        with pytest.raises(TranscriptionError):
+        with pytest.raises(TranscriptionError) as exc_info:
             transcribe_document_image(image_path, settings=settings, provider=provider)
+
+        assert exc_info.value.category.value == "external_provider_error"
+        assert exc_info.value.retriable is True
+        assert "retry" in exc_info.value.suggestion.lower()

tests/services/test_upload.py

@@ -16,7 +16,7 @@ class TestUploadValidation:
     def test_rejects_empty_bytes(self, session, tmp_path: Path):
         """create_upload_job rejects an empty upload payload."""
         settings = Settings(openrouter_api_key="test-key", upload_dir=tmp_path)
-        with pytest.raises(UploadError):
+        with pytest.raises(UploadError) as exc_info:
             create_upload_job(
                 filename="letter.jpg",
                 file_bytes=b"",
@@ -24,10 +24,13 @@ class TestUploadValidation:
                 settings=settings,
             )
 
+        assert exc_info.value.category.value == "validation_error"
+        assert "non-empty" in exc_info.value.suggestion.lower()
+
     def test_rejects_unsupported_extension(self, session, tmp_path: Path):
         """create_upload_job rejects unsupported filename extensions."""
         settings = Settings(openrouter_api_key="test-key", upload_dir=tmp_path)
-        with pytest.raises(UploadError):
+        with pytest.raises(UploadError) as exc_info:
             create_upload_job(
                 filename="notes.txt",
                 file_bytes=b"content",
@@ -35,6 +38,9 @@ class TestUploadValidation:
                 settings=settings,
             )
 
+        assert exc_info.value.category.value == "user_input_error"
+        assert "jpg" in exc_info.value.suggestion.lower()
+
 
 @pytest.mark.integration
 class TestUploadPersistence:

tests/services/test_worker.py

@@ -95,6 +95,9 @@ class TestWorkerFailurePath:
         assert transcript is not None
         assert transcript.text is None
         assert "provider failure" in transcript.error_detail
+        assert "[internal_unexpected_error]" in transcript.error_detail
+        assert "error_id=" in transcript.error_detail
+        assert "suggestion=" in transcript.error_detail
 
     def test_updates_existing_transcript_if_present(self, session, monkeypatch):
         """process_next_queued_job updates existing transcript instead of duplicating."""
@@ -118,6 +121,8 @@ class TestWorkerFailurePath:
         assert transcripts[0].id == existing.id
         assert transcripts[0].text is None
         assert "provider failure" in transcripts[0].error_detail
+        assert "[internal_unexpected_error]" in transcripts[0].error_detail
+        assert "error_id=" in transcripts[0].error_detail
 
 
 @pytest.mark.unit