{"record":{"id":"adb3ef7e872fccdb","repo":"Panniantong/Agent-Reach","slug":"provider-http-resp-status-code-resp-text-3","errorCode":null,"errorMessage":"{provider}: HTTP {resp.status_code}: {resp.text[:300]}","messagePattern":"(.+?): HTTP (.+?): (.+?)","errorType":"exception","errorClass":"TranscribeError","httpStatus":null,"severity":"error","filePath":"agent_reach/transcribe.py","lineNumber":393,"sourceCode":"            f\"{provider}: missing {PROVIDERS[provider]['key_field']} \"\n            f\"(configure with `agent-reach configure {provider}-key ...`)\"\n        )\n\n    info = PROVIDERS[provider]\n    with chunk.open(\"rb\") as fh:\n        try:\n            resp = requests.post(\n                info[\"endpoint\"],\n                headers={\"Authorization\": f\"Bearer {key}\"},\n                files={\"file\": (chunk.name, fh, \"audio/m4a\")},\n                data={\"model\": info[\"model\"], \"response_format\": \"text\"},\n                timeout=timeout,\n            )\n        except requests.RequestException as e:\n            raise TranscribeError(f\"{provider}: network error: {e}\") from e\n\n    if not resp.ok:\n        raise TranscribeError(f\"{provider}: HTTP {resp.status_code}: {resp.text[:300]}\")\n    return resp.text\n\n\ndef _provider_order(provider: str) -> List[str]:\n    if provider == \"auto\":\n        return [\"groq\", \"openai\"]\n    if provider in PROVIDERS:\n        return [provider]\n    raise TranscribeError(f\"unknown provider: {provider} (use groq|openai|auto)\")\n\n\ndef transcribe(\n    source: str,\n    *,\n    provider: str = \"auto\",\n    out_dir: Optional[Path] = None,\n    config: Optional[Config] = None,\n    allow_provider_fallback: bool = False,","sourceCodeStart":375,"sourceCodeEnd":411,"githubUrl":"https://github.com/Panniantong/Agent-Reach/blob/93ae1d18c37b707dec053c7c4f9d91cd8ef8943d/agent_reach/transcribe.py#L375-L411","documentation":"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...).","triggerScenarios":"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.","commonSituations":"Rotated or expired keys not re-configured; bursts of 24 chunks tripping rate limits; provider model renames after an API update; region-restricted keys.","solutions":["Read the embedded response body — it states the exact provider-side cause; fix that (re-configure key, wait out the rate window, etc.)","401/403: re-run agent-reach configure groq-key/openai-key with a valid key; verify with agent-reach doctor","429: retry with backoff, or set transcribe(..., provider='auto', allow_provider_fallback=True) so failed chunks go to the other provider","413: ensure you went through compress/chunk (32kbps, <=24 MiB) rather than feeding raw source audio"],"exampleFix":"# before\nfor chunk in chunks:\n    text += transcribe_chunk(chunk, \"groq\")  # HTTP 429 rate_limit_exceeded\n\n# after: fallback + backoff handled by the high-level API\nfrom agent_reach.transcribe import transcribe\ntext = transcribe(source_url, provider=\"auto\", allow_provider_fallback=True)","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"from agent_reach.transcribe import TranscribeError, transcribe_chunk\nimport time\n\ndef chunk_with_backoff(chunk, provider, attempts=4):\n    for i in range(attempts):\n        try:\n            return transcribe_chunk(chunk, provider)\n        except TranscribeError as e:\n            if \"HTTP 429\" in str(e) and i < attempts - 1:\n                time.sleep(2 ** i * 5)\n                continue\n            raise  # 401/413/etc. are not retried — fix key or chunk size","preventionTips":["Parse the status code from the message and only retry 429/5xx","Configure both provider keys so transcribe(..., provider='auto', allow_provider_fallback=True) can absorb outages","Keep chunks within the 32kbps/24 MiB envelope by using the built-in compress/chunk path"],"tags":["http","api-error","rate-limit","provider","transcription"],"backgroundTag":null,"analyzedSha":"93ae1d18c37b707dec053c7c4f9d91cd8ef8943d","analyzedAt":"2026-08-14T22:54:06.735Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}