datawhalechina/hello-agents · error · RuntimeError

API 请求频率已达上限（429 Too Many Requests）。\nSemantic Scholar 免费额度为

Error message

API 请求频率已达上限（429 Too Many Requests）。\nSemantic Scholar 免费额度为 100 次/5 分钟。\n请稍等 1-5 分钟后重试，或申请免费 API Key：\nhttps://www.semanticscholar.org/product/api\n获取后在 .env 中设置 SEMANTIC_SCHOLAR_API_KEY

What it means

The Semantic Scholar literature tool raises RuntimeError with HTTP 429 context after its retry loop (max_retries attempts with 2s/4s/8s exponential backoff) still receives 429 responses. The unauthenticated free tier is limited to 100 requests per 5-minute window, so sustained querying exhausts it.

Source

Thrown at Co-creation-projects/chengH425-PaperAssistant/src/literature_tool.py:209

                    headers={
                        "User-Agent": "PaperAssistant/1.0",
                        "Accept": "application/json"
                    }
                )
                if api_key:
                    req.add_header("x-api-key", api_key)

                with urllib.request.urlopen(req, timeout=20) as resp:
                    return json.loads(resp.read().decode("utf-8"))

            except urllib.error.HTTPError as e:
                if e.code == 429:
                    # 速率限制：等待后重试
                    wait = 2 ** (attempt + 1)  # 2s, 4s, 8s
                    if attempt < max_retries - 1:
                        time.sleep(wait)
                        continue
                    raise RuntimeError(
                        "API 请求频率已达上限（429 Too Many Requests）。\n"
                        "Semantic Scholar 免费额度为 100 次/5 分钟。\n"
                        "请稍等 1-5 分钟后重试，或申请免费 API Key：\n"
                        "https://www.semanticscholar.org/product/api\n"
                        "获取后在 .env 中设置 SEMANTIC_SCHOLAR_API_KEY"
                    ) from e
                raise RuntimeError(
                    f"Semantic Scholar API 返回 HTTP {e.code}: {e.reason}"
                ) from e
            except urllib.error.URLError as e:
                last_error = e
                if attempt < max_retries - 1:
                    time.sleep(2 ** (attempt + 1))
                    continue
                raise RuntimeError(f"网络连接失败: {str(e.reason)}") from e

        raise RuntimeError(f"请求失败（已重试 {max_retries} 次）: {last_error}")

View on GitHub (pinned to 606a07d341)

Solutions

1. Request a free API key at https://www.semanticscholar.org/product/api and set `SEMANTIC_SCHOLAR_API_KEY` in .env.
2. Wait 1-5 minutes for the 5-minute window to reset before retrying.
3. Reduce query volume: batch fewer keywords per turn, raise `max_results` instead of issuing many narrow queries.
4. Longer term: increase the backoff ceiling (e.g. 30-60s) so retries can cross the rate-limit window.

Example fix

// before
wait = 2 ** (attempt + 1)  # 2s, 4s, 8s

# after
wait = min(2 ** (attempt + 1), 60)  # cap backoff so retries can outlast the 5-min window

import time

def rate_budget_ok(call_count: list, window_start: list, limit: int = 95, window_s: int = 300) -> bool:
    """Track client-side request count against the 100/5min free-tier budget."""
    now = time.time()
    if now - window_start[0] > window_s:
        window_start[0], call_count[0] = now, 0
    return call_count[0] < limit

try:
    results = lit_tool.run({"keyword": kw})
except RuntimeError as e:
    if "429" in str(e):
        time.sleep(300)  # let the 5-minute window fully reset
        results = lit_tool.run({"keyword": kw})
    else:
        raise

When it happens

Trigger: Running multiple `literature_search` tool calls in quick succession (batch literature reviews, agent loops issuing several searches per turn) exceeds 100 requests/5 min without an API key; retries with short backoff fire inside the same throttled window and also get 429'd.

Common situations: Agent-driven workflows that fan out many keyword searches; shared IP/NAT with other users burning the same quota; missing `SEMANTIC_SCHOLAR_API_KEY` in .env.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• ArXiv API请求失败: {response.status}
• IEEE API请求失败: {response.status}
• TMDB 请求超时: {e}
• TMDB 请求失败: HTTP {resp.status_code}, {resp.text[:200]}
• Semantic Scholar API 返回 HTTP {e.code}: {e.reason}

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