From 1805ce8e67881b75eac7b6f8cb2030e88d8718a3 Mon Sep 17 00:00:00 2001
From: Jacob Lasky <jacob.s.lasky@gmail.com>
Date: Sat, 25 Jul 2026 13:21:37 -0400
Subject: [PATCH] fix(params): gate params by mode per Deepgram's docs, and
 report real errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Live-testing the keyterm fix against production turned up four separate defects,
all of them the same shape: the app sends something Deepgram refuses, and the
user is told nothing useful.

**Mode gating was materially wrong.** STREAMING_ONLY and BATCH_ONLY were
partial. Deepgram's docs carry a machine-readable capability matrix — each STT
feature page includes `stt-stream-unavailable` / `stt-batch-unavailable` markers
— and transcribing it adds filler_words, measurements, utt_split and
detect_language to BATCH_ONLY, and channels, encoding and sample_rate to
STREAMING_ONLY. This matters because a batch-only param sent to a stream is
SILENTLY IGNORED: the feature you believe you are testing was never applied, and
the run still looks valid. Same failure mode as the keyterms bug.

**The UI's own defaults produced a live 400.** sample_rate and channels render
as 0 when unset and were forwarded verbatim; Deepgram returns 400 for
`sample_rate=0`. A test actually asserted this was correct ("callers are
responsible for omitting defaults") — no caller did. Fixed with an explicit
ZERO_MEANS_UNSET set rather than a blanket drop-all-zeroes rule, because
`endpointing=0` is meaningful: it disables endpointing.

**Errors were replaced with a link to MDN.** The batch handler returned
str(httpx.HTTPStatusError), i.e. "Client error '400 Bad Request' for url ... For
more information check: <MDN 400 page>". That names neither the parameter nor
the reason, in an app whose entire purpose is explaining why Deepgram rejected a
request. _clean_error now surfaces Deepgram's response body (err_msg/err_code).
Response bodies are safe to show; the existing header stripping, which keeps the
server's API key out of responses, is unchanged and now has a test.

**An immediate stream close looked like a clean shutdown.** Deepgram refuses an
unsupported param on a WebSocket by completing the handshake and then closing
with code 1000 and no reason, so the user saw only "received 1000 (OK); then
sent 1000 (OK)". _clean_error now explains that a reasonless close means a
rejected parameter and tells the user to re-run in batch mode, where Deepgram
states the actual reason.

Batch-only controls (Filler Words, Utterances, Paragraphs) are now hidden while
streaming instead of offered and silently ignored.

Live verification against production, real Deepgram key:

    batch   keyterms=[perineorrhaphy]  -> "a perineorrhaphy"   (correct)
    batch   no keyterms (control)      -> "a perineurope"      (wrong)

That is the delta the earlier -rrhaphy CSVs could never show, since both of
their arms ran with no keyterms applied.

    alternatives=2  nova-3   -> 400      alternatives=2  base      -> 200
    alternatives=2  nova-2   -> 400      alternatives=2  enhanced  -> 200

`alternatives` is MODEL-dependent, not mode-dependent, in both batch and
streaming. It is deliberately NOT mode-gated and NOT removed: it is valid on
legacy models, which replicating a legacy customer config requires. An earlier
draft of this change had it batch-only, which the model sweep disproved; the
test now pins that distinction so it is not "corrected" back.

UI artifact: scripts/probe_ui.py gains --mode and --expect-removed, splits
"hidden from the user" from "gone entirely", and asserts on VISIBLE labels
rather than DOM presence, since a mode-gated control is still in the DOM.
Verified in both modes: the three controls are hidden in streaming and present
in batch, no console errors.

112 passed, 1 skipped.
---
 app.py                      |  49 ++++++++++++++++-
 scripts/probe_ui.py         | 104 ++++++++++++++++++++++++++++--------
 stt/options.py              |  49 +++++++++++++++--
 templates/index.html        |  13 +++--
 tests/test_options.py       |  66 ++++++++++++++++++++---
 tests/test_wire_contract.py |  77 +++++++++++++++++++++++++-
 6 files changed, 317 insertions(+), 41 deletions(-)

diff --git a/app.py b/app.py
index 823be59..5390f18 100644
--- a/app.py
+++ b/app.py
@@ -324,7 +324,50 @@ def _safe_temp_path(filename: str) -> Path:
 app = socketio.ASGIApp(sio, fastapi_app)
 
 def _clean_error(e: Exception) -> str:
-    """Strip SDK request headers (including auth token) from Deepgram exception messages."""
+    """Turn a Deepgram failure into the most specific message we can safely show.
+
+    DO NOT weaken the header stripping below. SDK exception messages embed the
+    full request, Authorization header included, so returning str(e) verbatim
+    would put the server's API key in an HTTP response body.
+
+    For httpx failures we substitute Deepgram's RESPONSE body, which is where the
+    actual reason lives. str(HTTPStatusError) is only
+        Client error '400 Bad Request' for url '...'
+        For more information check: https://developer.mozilla.org/...
+    which names neither the offending parameter nor the reason, and an MDN link
+    to "what is a 400" is worse than useless in a diagnostic tool: the whole
+    point of this app is to tell someone WHY Deepgram rejected their request.
+    A response body is safe to surface — credentials travel in request headers.
+    """
+    if isinstance(e, httpx.HTTPStatusError):
+        status = e.response.status_code
+        try:
+            body = e.response.json()
+            detail = body.get("err_msg") or body.get("error") or body.get("message")
+            code = body.get("err_code")
+            if detail:
+                return f"Deepgram {status}: {detail}" + (f" ({code})" if code else "")
+            return f"Deepgram {status}: {json_mod.dumps(body)[:500]}"
+        except ValueError:
+            text = (e.response.text or "").strip()
+            return f"Deepgram {status}: {text[:500]}" if text else f"Deepgram {status}"
+
+    if isinstance(e, websockets.exceptions.ConnectionClosed):
+        # Deepgram rejects an unsupported parameter on a STREAM by completing the
+        # handshake and then closing with code 1000 and NO reason, so websockets
+        # reports only "received 1000 (OK); then sent 1000 (OK)". That names
+        # neither the parameter nor the cause, and it reads like a clean shutdown
+        # rather than a rejection. Verified live: alternatives=2 on nova-3 closes
+        # this way, while the same request in batch mode returns a 400.
+        return (
+            f"Deepgram closed the stream immediately without transcribing ({e}). "
+            "A close with no reason is what an unsupported parameter looks like on "
+            "a stream — most often a parameter the chosen model does not accept "
+            "(e.g. alternatives>1 on nova-*, which is valid on base and enhanced). "
+            "Re-run the same parameters in batch mode: there Deepgram returns a "
+            "400 stating the actual reason."
+        )
+
     msg = str(e)
     m = re.search(r'status_code:\s*(\d+),\s*body:\s*(.+)$', msg, re.DOTALL)
     if m:
@@ -696,7 +739,9 @@ async def _batch_pipeline():
             return JSONResponse({"batch": batch_result, "streaming": stream_result})
 
     except httpx.HTTPStatusError as e:
-        return JSONResponse({"error": str(e)}, status_code=e.response.status_code)
+        # _clean_error, never str(e): it surfaces Deepgram's reason and strips
+        # request headers. This handler used str(e) and returned an MDN link.
+        return JSONResponse({"error": _clean_error(e)}, status_code=e.response.status_code)
     except Exception as e:
         return JSONResponse({"error": _clean_error(e)}, status_code=500)
 
diff --git a/scripts/probe_ui.py b/scripts/probe_ui.py
index 303bd7c..661f95f 100644
--- a/scripts/probe_ui.py
+++ b/scripts/probe_ui.py
@@ -12,7 +12,12 @@
     DEEPGRAM_API_KEY=probe-key uv run uvicorn app:app --port 8899
     # Terminal 2
     uv run python scripts/probe_ui.py
-    uv run python scripts/probe_ui.py --expect-absent Keywords --expect-present Keyterms
+    uv run python scripts/probe_ui.py --expect-removed Keywords --expect-present Keyterms
+    uv run python scripts/probe_ui.py --mode streaming \
+        --expect-absent "Filler Words" Utterances Paragraphs
+
+Exits non-zero when an expectation is unmet, so it works as a gate rather than
+just a screenshot printer.
 
 Requires the browser binary once: `uv run playwright install chromium`.
 
@@ -30,7 +35,18 @@
 ARTIFACTS = Path(__file__).resolve().parent / "probe-artifacts"
 
 
-async def probe(url: str, expect_present: list[str], expect_absent: list[str]) -> int:
+def _param_key(label: str) -> str:
+    """UI label -> Alpine params key. "Filler Words" -> "filler_words"."""
+    return label.strip().lower().replace(" ", "_")
+
+
+async def probe(
+    url: str,
+    expect_present: list[str],
+    expect_absent: list[str],
+    expect_removed: list[str],
+    mode: str | None,
+) -> int:
     ARTIFACTS.mkdir(exist_ok=True)
     failures: list[str] = []
 
@@ -58,19 +74,36 @@ async def probe(url: str, expect_present: list[str], expect_absent: list[str]) -
         await page.wait_for_timeout(1200)
 
         # Expand every collapsible param section, or a field can be "absent"
-        # only because its accordion happened to be shut.
-        await page.evaluate("""() => {
+        # only because its accordion happened to be shut. Some params are
+        # mode-gated (batch-only features are hidden while streaming), so --mode
+        # picks which surface is being asserted.
+        await page.evaluate(
+            """(m) => {
             const d = Alpine.$data(document.querySelector('[x-data]'));
+            if (m) d.mode = m;
             Object.keys(d.sections || {}).forEach(k => d.sections[k] = true);
-        }""")
-        await page.wait_for_timeout(700)
-
-        labels = await page.eval_on_selector_all(
-            ".field-label", "els => els.map(e => e.textContent.trim())"
-        )
-        bindings = await page.eval_on_selector_all(
-            "[x-model]", "els => els.map(e => e.getAttribute('x-model'))"
+        }""",
+            mode,
         )
+        await page.wait_for_timeout(700)
+        if mode:
+            print(f"mode: {mode}")
+
+        # VISIBLE labels only, and both label flavours (field rows use
+        # .field-label, checkboxes use <label for>). A mode-gated control is
+        # still in the DOM with x-show false, so presence is not the question —
+        # whether the user can see it is.
+        labels = await page.evaluate("""() => {
+            const seen = document.querySelectorAll('.field-label, .checkbox-item label');
+            return [...seen]
+                .filter(e => e.offsetParent !== null)
+                .map(e => e.textContent.trim());
+        }""")
+        bindings = await page.evaluate("""() => {
+            return [...document.querySelectorAll('[x-model]')]
+                .filter(e => e.offsetParent !== null)
+                .map(e => e.getAttribute('x-model'));
+        }""")
         params = await page.evaluate(
             "() => JSON.parse(JSON.stringify("
             "Alpine.$data(document.querySelector('[x-data]')).params))"
@@ -86,20 +119,34 @@ async def probe(url: str, expect_present: list[str], expect_absent: list[str]) -
             if name not in labels:
                 failures.append(f"expected field {name!r} to render; it did not")
 
+        # Two distinct kinds of absence, deliberately NOT conflated:
+        #  --expect-absent   not visible to the user (e.g. a batch-only control
+        #                    while streaming). The param legitimately stays in
+        #                    Alpine state; only the control is hidden.
+        #  --expect-removed  gone entirely — no label, no binding, and not in
+        #                    state. A removed label with a live binding left
+        #                    behind still ships the param, which is the failure
+        #                    the state check catches.
         for name in expect_absent:
-            # Check the label, the x-model binding, AND the live Alpine state.
-            # A removed label with a live binding left behind still ships the
-            # param, which is the failure this triple-check catches.
-            key = name.lower()
+            key = _param_key(name)
+            if name in labels:
+                failures.append(f"{name!r} is still visible")
+            if f"params.{key}" in bindings:
+                failures.append(f"{name!r} still has a visible x-model binding")
+
+        for name in expect_removed:
+            key = _param_key(name)
             if name in labels:
-                failures.append(f"{name!r} still has a rendered label")
+                failures.append(f"{name!r} is still visible")
             if f"params.{key}" in bindings:
-                failures.append(f"{name!r} still has an x-model binding")
+                failures.append(f"{name!r} still has a visible x-model binding")
             if key in params:
                 failures.append(f"{key!r} is still in the live Alpine params state")
 
-        await page.screenshot(path=str(ARTIFACTS / "ui_full.png"), full_page=True)
-        print(f"\nartifact: {ARTIFACTS / 'ui_full.png'}")
+        # Mode in the filename so a streaming run does not overwrite a batch one.
+        shot = ARTIFACTS / f"ui_{mode or 'default'}.png"
+        await page.screenshot(path=str(shot), full_page=True)
+        print(f"\nartifact: {shot}")
         await browser.close()
 
     if failures:
@@ -115,9 +162,22 @@ def main() -> int:
     ap = argparse.ArgumentParser()
     ap.add_argument("--url", default="http://127.0.0.1:8899/")
     ap.add_argument("--expect-present", nargs="*", default=[])
-    ap.add_argument("--expect-absent", nargs="*", default=[])
+    ap.add_argument(
+        "--expect-absent", nargs="*", default=[],
+        help="not visible to the user; may still exist in Alpine state (mode-gated)",
+    )
+    ap.add_argument(
+        "--expect-removed", nargs="*", default=[],
+        help="gone entirely: no label, no binding, and not in Alpine state",
+    )
+    ap.add_argument(
+        "--mode", default=None,
+        help="set the app mode first (streaming|batch); some controls are mode-gated",
+    )
     a = ap.parse_args()
-    return asyncio.run(probe(a.url, a.expect_present, a.expect_absent))
+    return asyncio.run(
+        probe(a.url, a.expect_present, a.expect_absent, a.expect_removed, a.mode)
+    )
 
 
 if __name__ == "__main__":
diff --git a/stt/options.py b/stt/options.py
index ad584eb..005a1c7 100644
--- a/stt/options.py
+++ b/stt/options.py
@@ -8,11 +8,50 @@ class Mode(str, Enum):
     BOTH = "both"
 
 
-# Params that are ONLY valid in streaming mode
-STREAMING_ONLY = {"interim_results", "vad_events", "endpointing", "utterance_end_ms", "no_delay"}
+# Mode gating, taken from Deepgram's own docs capability matrix. Each STT feature
+# page carries machine-readable markers, e.g. filler-words.mdx has
+#   <Markdown src="/snippets/stt-batch-available.mdx" />
+#   <Markdown src="/snippets/stt-stream-unavailable.mdx" />
+# so these two sets are transcribed from `stt-stream-unavailable` and
+# `stt-batch-unavailable` respectively. DO NOT add a param here from memory:
+# check the feature's page in deepgram-docs, because guessing wrong in either
+# direction is invisible. Sending a batch-only param to streaming is SILENTLY
+# IGNORED (the feature you think you are testing was never applied), and
+# stripping a param that is actually valid is equally silent.
+#
+# Params that are ONLY valid in streaming mode (docs: stt-batch-unavailable)
+STREAMING_ONLY = {
+    "interim_results",
+    "vad_events",
+    "endpointing",
+    "utterance_end_ms",
+    "no_delay",
+    "channels",
+    "encoding",
+    "sample_rate",
+}
+
+# Params that are ONLY valid in batch mode (docs: stt-stream-unavailable)
+BATCH_ONLY = {
+    "paragraphs",
+    "topics",
+    "intents",
+    "sentiment",
+    "utterances",
+    "filler_words",
+    "measurements",
+    "utt_split",
+    "detect_language",
+}
 
-# Params that are ONLY valid in batch mode
-BATCH_ONLY = {"paragraphs", "topics", "intents", "sentiment", "utterances"}
+# Numeric params where the UI's default of 0 means "unset", not "zero". Both of
+# these fields render as 0 in the params panel, and Deepgram returns 400 for
+# `sample_rate=0` or `channels=0`, so forwarding the default broke every batch
+# request that touched them.
+#
+# DO NOT generalise this to "drop all zeroes". `endpointing=0` is meaningful: it
+# disables endpointing. That is why this is an explicit set and not a rule.
+ZERO_MEANS_UNSET = {"sample_rate", "channels", "alternatives"}
 
 # Params that should never be sent to Deepgram (handled by client)
 INTERNAL_PARAMS = {"base_url"}
@@ -111,6 +150,8 @@ def clean_params(params: dict, mode: Mode) -> dict:
             continue
         if isinstance(value, bool) and not value:
             continue
+        if wire in ZERO_MEANS_UNSET and value in (0, "0"):
+            continue
         _put(result, wire, value)
 
     # Handle extra params: merge into result. `extra` is the deliberate escape
diff --git a/templates/index.html b/templates/index.html
index f5c7b80..625f3cf 100644
--- a/templates/index.html
+++ b/templates/index.html
@@ -1285,7 +1285,11 @@
                 <input type="checkbox" id="numerals" x-model="params.numerals">
                 <label for="numerals">Numerals</label>
               </div>
-              <div class="checkbox-item">
+              <!-- Batch only (docs: stt-stream-unavailable). Hidden rather than
+                   shown-and-ignored: Deepgram drops a stream-unavailable param
+                   silently, so a checkbox that does nothing reads as a broken
+                   feature. stt/options.py BATCH_ONLY strips it server-side. -->
+              <div class="checkbox-item" x-show="mode === 'batch'">
                 <input type="checkbox" id="filler_words" x-model="params.filler_words">
                 <label for="filler_words">Filler Words</label>
               </div>
@@ -1323,11 +1327,14 @@
                 <input type="checkbox" id="detect_entities" x-model="params.detect_entities">
                 <label for="detect_entities">Detect Entities</label>
               </div>
-              <div class="checkbox-item">
+              <!-- Batch only (docs: stt-stream-unavailable), same reasoning as
+                   Filler Words above: silently ignored on a stream, so hide it
+                   rather than offer a control that cannot work. -->
+              <div class="checkbox-item" x-show="mode === 'batch'">
                 <input type="checkbox" id="utterances" x-model="params.utterances">
                 <label for="utterances">Utterances</label>
               </div>
-              <div class="checkbox-item">
+              <div class="checkbox-item" x-show="mode === 'batch'">
                 <input type="checkbox" id="paragraphs" x-model="params.paragraphs">
                 <label for="paragraphs">Paragraphs</label>
               </div>
diff --git a/tests/test_options.py b/tests/test_options.py
index ca80b48..cde024f 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -17,11 +17,30 @@ def test_removes_falsy_values():
     assert result["model"] == "nova-3"
 
 
-def test_keeps_zero_numerics():
-    # clean_params does NOT strip 0 — callers are responsible for omitting defaults
-    result = clean_params({"alternatives": 0, "channels": 0}, Mode.STREAMING)
-    assert result["alternatives"] == 0
-    assert result["channels"] == 0
+def test_zero_is_dropped_only_where_zero_means_unset():
+    """The UI renders sample_rate, channels and alternatives as 0 when unset, and
+    Deepgram returns 400 for sample_rate=0 / channels=0 — verified live. So 0 on
+    those is "omit", not "zero".
+
+    This test previously asserted the opposite ("callers are responsible for
+    omitting defaults"). No caller did, so the UI's own defaults produced a live
+    400 on every batch request that touched them.
+    """
+    result = clean_params(
+        {"alternatives": 0, "channels": 0, "sample_rate": 0}, Mode.STREAMING
+    )
+    assert result == {}
+
+    # A non-zero value still goes through; only the sentinel is dropped.
+    result = clean_params({"channels": 2, "sample_rate": 16000}, Mode.STREAMING)
+    assert result == {"channels": 2, "sample_rate": 16000}
+
+
+def test_zero_is_preserved_where_zero_is_meaningful():
+    """DO NOT generalise the rule above to all zeroes. endpointing=0 disables
+    endpointing, so dropping it would silently change behaviour."""
+    result = clean_params({"endpointing": 0}, Mode.STREAMING)
+    assert result["endpointing"] == 0
 
 
 def test_removes_false_booleans():
@@ -155,12 +174,43 @@ def test_sdk_accepts_every_serialized_param_name():
     assert via_kwargs <= accepted, f"would raise TypeError at connect(): {sorted(via_kwargs - accepted)}"
     dropped = emitted - via_kwargs - via_query
     assert not dropped, f"params silently dropped, never reaching Deepgram: {sorted(dropped)}"
-    # These are real Deepgram params the SDK does not enumerate; they must be
-    # routed, not lost. Regression guard for the keyterms crash class.
-    for name in ("filler_words", "no_delay", "word_confidence"):
+    # Real Deepgram params the SDK does not enumerate; they must be routed, not
+    # lost. Regression guard for the keyterms crash class. filler_words is NOT in
+    # this list: Deepgram's docs mark it stream-unavailable, so it is stripped in
+    # streaming mode by design — see test_stream_unavailable_params_are_stripped.
+    for name in ("no_delay", "word_confidence", "diarize_version", "entity_prompt"):
         assert name in via_query, f"{name} is not being forwarded"
 
 
+def test_stream_unavailable_params_are_stripped_in_streaming():
+    """Deepgram's docs mark these stream-unavailable, and a batch-only param sent
+    to a stream is SILENTLY IGNORED — so leaving them in meant the feature under
+    test was never applied and the run looked valid. Batch keeps them."""
+    from stt.options import clean_params, Mode
+    for name in ("filler_words", "measurements", "utt_split", "detect_language"):
+        assert name not in clean_params({name: True}, Mode.STREAMING), name
+        assert name in clean_params({name: True}, Mode.BATCH), name
+
+
+def test_batch_unavailable_params_are_stripped_in_batch():
+    """Docs mark these batch-unavailable. sample_rate and channels additionally
+    returned a live 400 from Deepgram when forwarded to batch."""
+    from stt.options import clean_params, Mode
+    for name, value in (("channels", 2), ("encoding", "linear16"), ("sample_rate", 16000)):
+        assert name not in clean_params({name: value}, Mode.BATCH), name
+        assert name in clean_params({name: value}, Mode.STREAMING), name
+
+
+def test_alternatives_is_not_mode_gated():
+    """`alternatives` is MODEL-dependent, not mode-dependent, and this distinction
+    cost a wrong fix. alternatives=2 returns 400 on nova-3/nova-2 but 200 on base
+    and enhanced, in BOTH batch and streaming (verified live). Mode-gating it
+    would break the legacy-model config replication this tool exists to do."""
+    from stt.options import clean_params, Mode
+    for mode in (Mode.BATCH, Mode.STREAMING):
+        assert clean_params({"alternatives": 2}, mode) == {"alternatives": 2}
+
+
 def test_nova2_keywords_is_not_supported():
     """Deliberately dropped. `keywords` is Nova-2-and-older keyword BOOSTING
     (`keywords=TERM:INTENSIFIER`); this app targets Nova-3 and Flux, where the
diff --git a/tests/test_wire_contract.py b/tests/test_wire_contract.py
index bbaaf64..d799a05 100644
--- a/tests/test_wire_contract.py
+++ b/tests/test_wire_contract.py
@@ -84,7 +84,6 @@ async def test_passthrough_params_reach_the_wire():
     """
     params = {
         "model": "nova-3",
-        "filler_words": True,
         "no_delay": True,
         "word_confidence": True,
         "alternatives": 3,
@@ -93,7 +92,6 @@ async def test_passthrough_params_reach_the_wire():
     }
     pairs = _pairs(await _handshake_path(params))
     for expected in (
-        ("filler_words", "true"),
         ("no_delay", "true"),
         ("word_confidence", "true"),
         ("alternatives", "3"),
@@ -102,6 +100,11 @@ async def test_passthrough_params_reach_the_wire():
     ):
         assert expected in pairs, f"{expected[0]} never reached the wire: {pairs}"
 
+    # filler_words is the sixth of that group, but Deepgram's docs mark it
+    # stream-unavailable, so on a STREAM it must be stripped rather than
+    # forwarded and silently ignored. It reaches the wire in batch mode instead.
+    assert "filler_words" not in [k for k, _ in pairs]
+
 
 @pytest.mark.asyncio
 async def test_keyterm_is_singular_and_repeated_per_term():
@@ -157,3 +160,73 @@ async def test_base_url_is_never_forwarded_to_deepgram():
     would leak internal endpoint names into Deepgram's request logs."""
     path = await _handshake_path({"model": "nova-3", "base_url": "api.deepgram.com"})
     assert "base_url" not in [k for k, _ in _pairs(path)]
+
+
+def test_clean_error_surfaces_deepgrams_reason_not_an_mdn_link():
+    """A diagnostic tool must report WHY Deepgram refused the request.
+
+    str(httpx.HTTPStatusError) is only "Client error '400 Bad Request' for url
+    ... For more information check: <MDN link>", which names neither the
+    parameter nor the cause. This handler used to return exactly that.
+    """
+    import httpx
+
+    import app as app_mod
+
+    request = httpx.Request("POST", "https://api.deepgram.com/v1/listen?alternatives=2")
+    response = httpx.Response(
+        400,
+        json={"err_code": "Bad Request", "err_msg": "alternatives is not supported for this model"},
+        request=request,
+    )
+    err = httpx.HTTPStatusError("boom", request=request, response=response)
+
+    msg = app_mod._clean_error(err)
+    assert "alternatives is not supported for this model" in msg
+    assert "Deepgram 400" in msg
+    assert "developer.mozilla.org" not in msg
+
+
+def test_clean_error_handles_a_non_json_body():
+    import httpx
+
+    import app as app_mod
+
+    request = httpx.Request("POST", "https://api.deepgram.com/v1/listen")
+    response = httpx.Response(502, text="upstream unavailable", request=request)
+    err = httpx.HTTPStatusError("boom", request=request, response=response)
+    assert app_mod._clean_error(err) == "Deepgram 502: upstream unavailable"
+
+
+def test_clean_error_explains_an_immediate_stream_close():
+    """Deepgram rejects an unsupported param on a stream by closing with 1000 and
+    no reason, which websockets reports as "received 1000 (OK)". That reads like a
+    clean shutdown, so the message must say it is a rejection and how to get the
+    real reason."""
+    import websockets.exceptions
+    import websockets.frames
+
+    import app as app_mod
+
+    # Reproduces the exact shape seen in production: close received, then sent,
+    # both code 1000 with an empty reason. rcvd_then_sent must be non-None when
+    # both frames are present (websockets asserts this).
+    close = websockets.frames.Close(1000, "")
+    err = websockets.exceptions.ConnectionClosedOK(close, close, True)
+    msg = app_mod._clean_error(err)
+    assert "closed the stream immediately" in msg
+    assert "batch mode" in msg  # tells the user how to get the actual reason
+
+
+def test_clean_error_still_strips_sdk_request_headers():
+    """Load-bearing: SDK exception messages embed the full request including the
+    Authorization header, so this must never degrade into returning str(e)."""
+    import app as app_mod
+
+    e = Exception(
+        "ApiError: request: POST /v1/listen headers: {'Authorization': 'Token sk-secret'} "
+        "status_code: 401, body: {'err_msg': 'Invalid credentials'}"
+    )
+    msg = app_mod._clean_error(e)
+    assert "sk-secret" not in msg
+    assert "Invalid credentials" in msg