datawhalechina/hello-agents · error · MovieServiceError

TMDB 请求超时: {e}

Error message

TMDB 请求超时: {e}

What it means

MovieServiceError raised when the httpx client's GET to TMDB raises httpx.TimeoutException — the request exceeded the 30-second timeout configured on httpx.Client(timeout=30.0). Default status code is likely 503/500 class; it signals a slow upstream, not a code bug. Chained with `from e` so the specific timeout subtype (ConnectTimeout, ReadTimeout) is preserved.

Source

Thrown at Co-creation-projects/aatanxiao12-beep-YingQian/backend/app/services/movie_service.py:118

        if token:
            headers["Authorization"] = f"Bearer {token}"
        else:
            params["api_key"] = api_key  # type: ignore[assignment]
        return headers, params

    def _get(self, path: str, extra_params: Optional[Dict[str, Any]] = None) -> dict:
        """对 TMDB 发 GET，统一处理超时、网络错误与非 2xx / 非 JSON。"""
        headers, params = self._auth_headers_and_params()
        if extra_params:
            for k, v in extra_params.items():
                if v is not None and v != "":
                    params[k] = v

        url = f"{TMDB_API_BASE}{path}"
        try:
            resp = self._client.get(url, headers=headers, params=params)
        except httpx.TimeoutException as e:
            raise MovieServiceError(f"TMDB 请求超时: {e}") from e
        except httpx.HTTPError as e:
            raise MovieServiceError(f"TMDB 网络错误: {e}") from e

        if resp.status_code == 401:
            raise MovieServiceError(
                "TMDB 鉴权失败：请检查 Access Token / API Key",
                status_code=401,
            )
        if resp.status_code == 404:
            raise MovieServiceError("影片不存在或已下架", status_code=404)
        if resp.status_code >= 400:
            raise MovieServiceError(
                f"TMDB 请求失败: HTTP {resp.status_code}, {resp.text[:200]}"
            )

        try:
            return resp.json()
        except ValueError as e:

View on GitHub (pinned to 606a07d341)

Solutions

1. Retry with backoff (e.g. 2 attempts, exponential) for idempotent GETs — transient timeouts dominate
2. Tune the timeout: use httpx.Timeout(10.0, read=30.0) with a snappier connect timeout so dead connections fail fast
3. If in a filtered network region, route via a proxy (HTTP_PROXY/HTTPS_PROXY or a self-hosted mirror) that can reach TMDB
4. Check TMDB status page and your rate-limit headers before assuming code issues

Example fix

# before
self._client = httpx.Client(timeout=30.0)
except httpx.TimeoutException as e:
    raise MovieServiceError(f"TMDB 请求超时: {e}") from e

# after
self._client = httpx.Client(
    timeout=httpx.Timeout(10.0, read=30.0, write=10.0, pool=10.0)
)
# in _get, wrap with a small retry:
for attempt in range(3):
    try:
        resp = self._client.get(url, headers=headers, params=params)
        break
    except httpx.TimeoutException as e:
        if attempt == 2:
            raise MovieServiceError(f"TMDB 请求超时（已重试3次）: {e}", status_code=504) from e
        time.sleep(2 ** attempt)

from app.services.movie_service import MovieServiceError
import time

for attempt in range(3):
    try:
        return service.get_detail(mid)
    except MovieServiceError as e:
        if '超时' not in str(e) or attempt == 2:
            raise
        time.sleep(2 ** attempt)

When it happens

Trigger: GET to api.themoviedb.org exceeding 30s during TMDB outages or rate-limit-induced throttling; client running in a network-restricted environment where connections stall (connect timeout to a blackholed IP); system under heavy load causing slow reads; DNS resolution hanging.

Common situations: Corporate proxy or firewall stalling outbound TLS; TMDB having a partial outage (check status.themoviedb.org); bursts of requests triggering server-side slowdown; GFW/network filtering in some regions causing connect hangs to TMDB.

Related errors

• TMDB 网络错误: {e}
• 工具 '{tool_name}' 执行超时
• TMDB 返回非 JSON
• API 请求频率已达上限（429 Too Many Requests）。\nSemantic Scholar 免费额度为
• 服务响应中断，请重试

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/4da14ca344d05e7e. Report an issue: GitHub.