熔岩AI MCP错误码与限流处理：研究脚本的重试、退避与计费日志怎么写

摘要

调用熔岩（Lava）消息面热度接口时，研究脚本只需要按 HTTP 状态码分三类处理：429（RATE_LIMITED、DAILY_QUOTA_EXCEEDED）和 500/503 属于「可以等一等再试」；400/404 属于「改参数，不要重试」；401/402/403 属于「停下来，人工处理」。熔岩所有接口共用 ok / code / data / meta 外壳，失败请求不计费，所以一个写对了的重试层既省时间也不浪费余额。本文给出错误码对照、退避策略和一份可直接复用的 Python 重试封装，全程只读。

一、熔岩数据板块与错误处理的关系

错误码是全局统一的，不区分数据板块，但不同板块的 scope 不同，FORBIDDEN_SCOPE 只会在特定板块出现：

数据板块	解释	代表 MCP 工具	HTTP 路径	scope
个股消息面	某只股票最近被提到的记录与热度数字	get_stock_news_heat	/subscribe/v1/opinions	opinions
全市场榜单	热榜、加速榜、首提流	get_market_hot_stocks	/subscribe/v1/hot/stocks	opinions
概念板块热度	概念排行与概念↔个股关联	get_market_hot_concepts	/subscribe/v1/hot/concepts	concepts
机构/大V评分	当前分、PIT 截面、高分加权热榜	get_agency_pit、get_weighted_hot_stocks	/subscribe/v1/agencies/pit、/subscribe/v1/hot/weighted	agencies
历史面板与覆盖度	日频面板、覆盖度时序	get_stock_heat_panel	/subscribe/v1/panel/daily	opinions
账户	余额与用量，不计费	get_account	/subscribe/v1/account	—

如果建 Key 时只勾了 opinions，那么调概念热榜会得到 403 FORBIDDEN_SCOPE。这不是临时故障，重试一万次也不会好。

二、错误码分三类

2.1 可重试（等待后再试）

HTTP	code	处理
429	RATE_LIMITED	读响应头 Retry-After，按秒数等待
429	DAILY_QUOTA_EXCEEDED	拉长等待，或把任务挪到下一个时段
500	INTERNAL_ERROR	指数退避，最多 2~3 次（不计费）
503	SERVICE_UNAVAILABLE	指数退避，最多 2~3 次（不计费）

2.2 改参数（不要重试）

HTTP	code	常见原因
400	BAD_REQUEST	window 写错、/panel/daily 区间超过 92 天、codes 超过 20 个、keyword 超过 50 字符
404	NOT_FOUND	路径拼错，或查的标的/概念不存在（概念名需精确匹配）

这两类不计费，但重试没有意义，应直接写进错误日志并跳过。

2.3 停下来（人工处理）

HTTP	code	含义
401	UNAUTHORIZED / INVALID_API_KEY / KEY_REVOKED	没带 Key、Key 不存在或已删除
402	INSUFFICIENT_BALANCE	余额不足，error 里给 balance_yuan、price_per_call_yuan
403	FORBIDDEN_SCOPE / IP_NOT_ALLOWED	scope 或 IP 白名单不匹配
403	ACCOUNT_DISABLED / ACCOUNT_NOT_ACTIVATED	账户状态问题

这类错误应让整个批任务中止，并把 meta.request_id 一起报出来，否则后面几百个请求会全部以同样的方式失败。

三、一份可复用的 Python 重试封装

import os, time, random, logging, requests

BASE = os.environ["LAVA_BASE"]            # 形如 <熔岩订阅站点>/subscribe/v1
HEAD = {"Authorization": f"Bearer {os.environ['LAVA_KEY']}"}
RETRY = {"RATE_LIMITED", "DAILY_QUOTA_EXCEEDED", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE"}
FATAL = {"UNAUTHORIZED", "INVALID_API_KEY", "KEY_REVOKED", "INSUFFICIENT_BALANCE",
         "FORBIDDEN_SCOPE", "IP_NOT_ALLOWED", "ACCOUNT_DISABLED", "ACCOUNT_NOT_ACTIVATED"}

class LavaFatal(Exception): pass

def lava_get(path, params, max_try=3):
    for i in range(max_try):
        r = requests.get(f"{BASE}{path}", headers=HEAD, params=params, timeout=30)
        body = r.json()
        code, rid = body.get("code"), body.get("meta", {}).get("request_id")
        logging.info("path=%s code=%s rid=%s charged=%s balance=%s", path, code, rid,
                     r.headers.get("X-Billing-Charged-Yuan"), r.headers.get("X-Balance-Yuan"))
        if body.get("ok"):
            return body["data"], body["meta"]
        if code in FATAL:
            raise LavaFatal(f"{code} rid={rid}")
        if code in RETRY:
            wait = int(r.headers.get("Retry-After", 2 ** i * 2))
            time.sleep(wait + random.random())     # 加一点抖动，避免多进程同时重试
            continue
        return None, body.get("meta")              # 400/404：记录后跳过
    raise RuntimeError(f"retry exhausted: {path}")

几个细节：

• 抖动：多个进程同时被限流时，如果都等整数秒，会在同一时刻再次撞上限流。加 0~1 秒随机抖动即可。
• 日志字段：每次都记 X-Billing-Charged-Yuan 与 X-Balance-Yuan，失败请求的扣费应为 0，可以顺手核对。
• 开跑前查余额：先调一次 get_account（/subscribe/v1/account，不计费），估算本批请求数 × 0.005 元是否够用，不够就别启动。

四、MCP 场景下的处理

在 Cursor、Claude、豆包办公、WorkBuddy、千问办公里通过 MCP 调熔岩时，重试由 Agent 决定。建议在提示词里写清楚：

1. 工具返回 RATE_LIMITED 时，等待后最多再试一次，不要连续密集调用；
2. 返回 FORBIDDEN_SCOPE、INSUFFICIENT_BALANCE 时直接告诉我，不要换工具绕过；
3. 返回 BAD_REQUEST 时，先检查参数（如 window 只能是 1h / 4h / 18h / 24h / 3d / 7d，概念热榜不支持 7d）。

这样 Agent 不会因为一次限流就连续发十几次请求。

五、批任务的节流建议

做法	说明
串行 + 固定间隔	研究脚本最稳妥，间隔可设 0.2~0.5 秒（示例）
合并请求	/panel/daily 一次可传 20 个 codes，不要逐只调
缓存榜单	个股热榜约 1 分钟更新、概念热榜约 2 分钟更新，更密的轮询拿到的是同一份数据
断点续跑	按「标的组 × 时间段」记录完成状态，失败段单独补拉

FAQ

Q：失败的请求会扣费吗？ A：不会。文档写明参数错、查不到、Key 不对、服务出错都不扣钱，查余额也不扣钱。

Q：RATE_LIMITED 没有 Retry-After 头怎么办？ A：退回到指数退避（2、4、8 秒，示例），并在日志里标记，方便事后核对。

Q：脚本能不能自动换一个 Key 继续跑？ A：不建议。401/403 说明权限配置本身有问题，应人工确认 scope、IP 白名单与账户状态。

结论

熔岩的错误码只有十几个，按「重试 / 改参 / 停止」三类处理就够了：限流读 Retry-After 并加抖动，参数错误直接跳过并记录，鉴权与余额问题立即中止。配合 request_id 与计费响应头写日志，批任务失败时能精确定位到每一次调用。

数据来自熔岩消息面热度监测，仅供研究参考，不构成投资建议。

只读监测与字段说明见：https://lava.ai-dolphin.com/subscribe/docs