claude-sonnet-5 review Phase 3 (by gpt-5.3-codex)

src/transcription/api/errors.py

@@ -21,7 +21,9 @@ _STATUS_BY_CATEGORY: dict[ErrorCategory, int] = {
     ErrorCategory.NOT_FOUND: 404,
     ErrorCategory.CONFLICT: 409,
     ErrorCategory.EXTERNAL_PROVIDER: 503,
+    ErrorCategory.EXTERNAL_TIMEOUT: 503,
     ErrorCategory.INFRA_TRANSIENT: 503,
+    ErrorCategory.PROCESSING: 500,
     ErrorCategory.INFRA_PERSISTENT: 500,
     ErrorCategory.INTERNAL_UNEXPECTED: 500,
 }

src/transcription/errors.py

@@ -17,6 +17,7 @@ class ErrorCategory(StrEnum):
     NOT_FOUND = "not_found_error"
     CONFLICT = "conflict_error"
     EXTERNAL_PROVIDER = "external_provider_error"
+    EXTERNAL_TIMEOUT = "external_timeout_error"
     PROCESSING = "processing_error"
     INFRA_TRANSIENT = "infrastructure_transient_error"
     INFRA_PERSISTENT = "infrastructure_persistent_error"
@@ -61,19 +62,19 @@ class ErrorEnvelope:
 
 def canonical_error_category(error: AppError) -> str:
     """Map internal categories to canonical API/UI envelope categories."""
-    match error.category:
-        case ErrorCategory.VALIDATION | ErrorCategory.USER_INPUT:
-            return "validation"
-        case ErrorCategory.NOT_FOUND:
-            return "not_found"
-        case ErrorCategory.CONFLICT:
-            return "conflict"
-        case ErrorCategory.EXTERNAL_PROVIDER:
-            return "external"
-        case ErrorCategory.INFRA_TRANSIENT:
-            return "timeout"
-        case _:
-            return "internal"
+    mapping: dict[ErrorCategory, str] = {
+        ErrorCategory.VALIDATION: "validation",
+        ErrorCategory.USER_INPUT: "validation",
+        ErrorCategory.NOT_FOUND: "not_found",
+        ErrorCategory.CONFLICT: "conflict",
+        ErrorCategory.EXTERNAL_PROVIDER: "external",
+        ErrorCategory.EXTERNAL_TIMEOUT: "timeout",
+        ErrorCategory.INFRA_TRANSIENT: "timeout",
+        ErrorCategory.PROCESSING: "internal",
+        ErrorCategory.INFRA_PERSISTENT: "internal",
+        ErrorCategory.INTERNAL_UNEXPECTED: "internal",
+    }
+    return mapping.get(error.category, "internal")
 
 
 def build_error_envelope(error: AppError) -> ErrorEnvelope:

src/transcription/services/store.py

@@ -122,9 +122,8 @@ async def create_document_job(
         _best_effort_delete(stored_path)
         raise SourceStorageError(
             "Failed to create Document, Source, and Job records",
-            category=ErrorCategory.INFRA_TRANSIENT,
+            category=ErrorCategory.INFRA_PERSISTENT,
             suggestion="Retry upload. If this keeps happening, verify database availability.",
-            retriable=True,
         ) from exc
 
     logger.info("Created document job document_id=%s job_id=%s", document.id, job.id)
@@ -200,9 +199,8 @@ async def create_job_for_document(
             _best_effort_delete(source.stored_path)
         raise SourceStorageError(
             "Failed to create Job records from Source files",
-            category=ErrorCategory.INFRA_TRANSIENT,
+            category=ErrorCategory.INFRA_PERSISTENT,
             suggestion="Retry creation. If this keeps happening, verify database availability.",
-            retriable=True,
         ) from exc
 
     logger.info("Created explicit job document_id=%s job_id=%s sources=%s", document_id, job.id, len(source_ids))

src/transcription/services/workflows.py

@@ -285,7 +285,7 @@ async def process_queued_job(  # noqa: PLR0915
         except TimeoutError:
             error = AppError(
                 f"Provider call timed out after {runtime_settings.worker_provider_timeout_seconds:.1f}s",
-                category=ErrorCategory.EXTERNAL_PROVIDER,
+                category=ErrorCategory.EXTERNAL_TIMEOUT,
                 suggestion="Retry the job. If this repeats, verify provider latency and request payload size.",
                 retriable=True,
             )