Add error handling for session bootstrap failures: Implement a client-safe error response payload in session_bootstrap.py and update Streamlit routes to use this new error handling.

src/api/session_bootstrap.py

@@ -25,6 +25,7 @@ RETRYABLE_TWIRP_CODES = {
     livekit_api.TwirpErrorCode.UNAVAILABLE,
     livekit_api.TwirpErrorCode.UNKNOWN,
 }
+CLIENT_BOOTSTRAP_ERROR_MESSAGE = "Could not initialize voice session. Please try again."
 
 
 @dataclass(frozen=True)
@@ -110,6 +111,14 @@ def _is_retryable_bootstrap_error(exc: Exception) -> bool:
     return False
 
 
+def build_bootstrap_error_payload(_: Exception | None = None) -> dict[str, str]:
+    """Build a client-safe error response payload without internal details."""
+    return {
+        "error": "bootstrap_failed",
+        "message": CLIENT_BOOTSTRAP_ERROR_MESSAGE,
+    }
+
+
 class _SessionBootstrapHandler(BaseHTTPRequestHandler):
     server_version = "OpenVoiceAgentBootstrap/1.0"
     protocol_version = "HTTP/1.1"
@@ -124,7 +133,7 @@ class _SessionBootstrapHandler(BaseHTTPRequestHandler):
         except Exception as exc:  # pragma: no cover - exercised by integration flow
             logger.exception("Failed to create session bootstrap payload: %s", exc)
             self._write_json(
-                {"error": "bootstrap_failed", "message": str(exc)},
+                build_bootstrap_error_payload(exc),
                 status=HTTPStatus.INTERNAL_SERVER_ERROR,
             )
             return

src/api/streamlit_routes.py

@@ -12,7 +12,10 @@ from streamlit.web.server.server_util import make_url_path_regex
 from tornado.routing import PathMatches, Rule
 from tornado.web import Application, RequestHandler
 
-from src.api.session_bootstrap import build_session_bootstrap_payload
+from src.api.session_bootstrap import (
+    build_bootstrap_error_payload,
+    build_session_bootstrap_payload,
+)
 from src.core.logger import logger
 
 SESSION_BOOTSTRAP_ENDPOINT = "session/bootstrap"
@@ -46,7 +49,7 @@ class SessionBootstrapRequestHandler(RequestHandler):
         except Exception as exc:  # pragma: no cover - integration behavior
             logger.exception("Failed to create session bootstrap payload: %s", exc)
             self._write_json(
-                {"error": "bootstrap_failed", "message": str(exc)},
+                build_bootstrap_error_payload(exc),
                 status=HTTPStatus.INTERNAL_SERVER_ERROR,
             )
             return

src/core/settings.py

@@ -14,21 +14,32 @@ ENV_FILE = BASE_DIR / ".env"
 load_dotenv(ENV_FILE, override=True)
 logger.info(f"Loaded environment from: {ENV_FILE}")
 
+SENSITIVE_KEY_MARKERS = ("key", "token", "secret", "password")
+
+
+def _is_sensitive_key(key: str) -> bool:
+    key_lower = key.lower()
+    return any(marker in key_lower for marker in SENSITIVE_KEY_MARKERS)
+
+
+def _redact_sensitive_value(value: object) -> str:
+    if value is None:
+        return "<not set>"
+    if isinstance(value, str) and not value:
+        return "<not set>"
+    return "<redacted>"
+
 
 def mask_sensitive_data(data: dict) -> dict:
     masked = {}
-    sensitive_keys = ["key", "token", "secret", "password"]
 
     for key, value in data.items():
+        if _is_sensitive_key(key):
+            masked[key] = _redact_sensitive_value(value)
+            continue
+
         if isinstance(value, dict):
             masked[key] = mask_sensitive_data(value)
-        elif isinstance(value, str) and any(s in key.lower() for s in sensitive_keys):
-            if not value:
-                masked[key] = "<not set>"
-            elif len(value) <= 4:
-                masked[key] = "***"
-            else:
-                masked[key] = f"{value[:4]}...{value[-4:]}"
         else:
             masked[key] = value
 
@@ -227,5 +238,13 @@ try:
     logger.info(f"Settings loaded: {json.dumps(masked_settings, indent=2)}")
 
 except ValidationError as e:
-    logger.exception(f"Error validating settings: {e.json()}")
+    safe_errors = e.errors(
+        include_url=False,
+        include_context=False,
+        include_input=False,
+    )
+    logger.exception(
+        "Error validating settings: %s",
+        json.dumps(safe_errors),
+    )
     raise

tests/test_session_bootstrap.py

@@ -173,3 +173,13 @@ def test_build_session_bootstrap_payload_does_not_retry_non_retryable_twirp_erro
 
     assert attempts == 1
     assert sleep_calls == []
+
+
+def test_build_bootstrap_error_payload_hides_exception_details() -> None:
+    payload = session_bootstrap.build_bootstrap_error_payload(
+        RuntimeError("NVIDIA_API_KEY=super-secret")
+    )
+
+    assert payload["error"] == "bootstrap_failed"
+    assert payload["message"] == session_bootstrap.CLIENT_BOOTSTRAP_ERROR_MESSAGE
+    assert "super-secret" not in payload["message"]