Panniantong/Agent-Reach · error · TranscribeError

{provider}: HTTP {resp.status_code}: {resp.text[:300]}

Error message

{provider}: HTTP {resp.status_code}: {resp.text[:300]}

What it means

Raised by transcribe_chunk (transcribe.py:392-393) when the provider returns a non-2xx HTTP status. The message includes status code plus the first 300 chars of the response body, which usually contains the provider's own error JSON (invalid_api_key, rate_limit_exceeded, file too large, model decommissioned...).

Source

Thrown at agent_reach/transcribe.py:393

            f"{provider}: missing {PROVIDERS[provider]['key_field']} "
            f"(configure with `agent-reach configure {provider}-key ...`)"
        )

    info = PROVIDERS[provider]
    with chunk.open("rb") as fh:
        try:
            resp = requests.post(
                info["endpoint"],
                headers={"Authorization": f"Bearer {key}"},
                files={"file": (chunk.name, fh, "audio/m4a")},
                data={"model": info["model"], "response_format": "text"},
                timeout=timeout,
            )
        except requests.RequestException as e:
            raise TranscribeError(f"{provider}: network error: {e}") from e

    if not resp.ok:
        raise TranscribeError(f"{provider}: HTTP {resp.status_code}: {resp.text[:300]}")
    return resp.text


def _provider_order(provider: str) -> List[str]:
    if provider == "auto":
        return ["groq", "openai"]
    if provider in PROVIDERS:
        return [provider]
    raise TranscribeError(f"unknown provider: {provider} (use groq|openai|auto)")


def transcribe(
    source: str,
    *,
    provider: str = "auto",
    out_dir: Optional[Path] = None,
    config: Optional[Config] = None,
    allow_provider_fallback: bool = False,

View on GitHub (pinned to 93ae1d18c3)

Solutions

  1. Read the embedded response body — it states the exact provider-side cause; fix that (re-configure key, wait out the rate window, etc.)
  2. 401/403: re-run agent-reach configure groq-key/openai-key with a valid key; verify with agent-reach doctor
  3. 429: retry with backoff, or set transcribe(..., provider='auto', allow_provider_fallback=True) so failed chunks go to the other provider
  4. 413: ensure you went through compress/chunk (32kbps, <=24 MiB) rather than feeding raw source audio

Example fix

# before
for chunk in chunks:
    text += transcribe_chunk(chunk, "groq")  # HTTP 429 rate_limit_exceeded

# after: fallback + backoff handled by the high-level API
from agent_reach.transcribe import transcribe
text = transcribe(source_url, provider="auto", allow_provider_fallback=True)
Defensive patterns

Strategy: fallback

Try / catch

from agent_reach.transcribe import TranscribeError, transcribe_chunk
import time

def chunk_with_backoff(chunk, provider, attempts=4):
    for i in range(attempts):
        try:
            return transcribe_chunk(chunk, provider)
        except TranscribeError as e:
            if "HTTP 429" in str(e) and i < attempts - 1:
                time.sleep(2 ** i * 5)
                continue
            raise  # 401/413/etc. are not retried — fix key or chunk size

Prevention

When it happens

Trigger: 401 with a revoked/wrong API key; 429 when Groq's free-tier rate limits hit during multi-chunk jobs; 413 if a chunk exceeds the provider's request-size ceiling; 404/400 when the configured model name (whisper-large-v3 / whisper-1) changes upstream.

Common situations: Rotated or expired keys not re-configured; bursts of 24 chunks tripping rate limits; provider model renames after an API update; region-restricted keys.

Related errors

AI-assisted analysis of Panniantong/Agent-Reach@93ae1d18c3 (2026-08-14). Data as JSON: /api/errors/adb3ef7e872fccdb. Report an issue: GitHub.