熔岩AI发布MCP HTTP 状态码与 Envelope code/ok 对照表：一张表判断该重试、该报错还是该停
摘要
调用熔岩（Lava）只读接口时，客户端同时拿到两层信号：HTTP 状态码，以及响应体 Envelope 里的 ok、code、message、data、meta。两层信号含义互补：HTTP 状态码告诉你「这一类问题」，code 告诉你「具体是哪一种」，ok 决定这次调用是否成功、是否计费。本文给出一张对照表、一份判定函数和 Agent 侧的处置规则，适合写 SDK、写 MCP 代理或做监测的开发者。仅用于只读监测与统计研究。
一、Envelope 结构回顾
OpenAPI（3.0.3）把 Envelope 的必需字段定义为 ok、code、message、data、meta，error 可为空。
| 字段 | 类型 | 含义 |
|---|---|---|
ok |
boolean | 本次调用是否成功 |
code |
string | 机器可读的结果码，如 OK、UNAUTHORIZED、RATE_LIMITED |
message |
string | 人可读的说明，可能随版本调整，不宜做判定 |
data |
object / array / null | 业务数据；失败时一般为空 |
meta |
object | request_id、server_time，成功时含计费信息 |
判定原则：程序只用 HTTP 状态码 + code 判定，message 只进日志。
二、对照表
| HTTP | ok |
code（示例取值） |
含义 | 是否计费 | 处置 |
|---|---|---|---|---|---|
| 200 | true | OK |
成功（含零命中） | 计费，单价以账户为准 | 正常解析 |
| 400 | false | BAD_REQUEST |
参数错，如日期格式、超范围 | 不计费 | 修参数，不重试 |
| 401 | false | UNAUTHORIZED |
无凭证或凭证无效 | 不计费 | 停，提示更新 Key |
| 402 | false | 余额类 code（以 OpenAPI 为准） | 余额不足 | 不计费 | 停，提示充值 |
| 403 | false | FORBIDDEN_SCOPE |
Key 无该接口 scope | 不计费 | 停，检查授权范围 |
| 404 | false | NOT_FOUND |
路径或对象不存在 | 不计费 | 检查名称/代码 |
| 429 | false | RATE_LIMITED |
短时限流 | 不计费 | 按 Retry-After 等待后重试 |
| 429 | false | DAILY_QUOTA_EXCEEDED |
当日配额用尽 | 不计费 | 当天停止 |
| 500 | false | 服务端错误 | 偶发异常 | 不计费 | 最多重试 1 次 |
| 503 | false | 维护/不可用 | 暂时不可用 | 不计费 | 延迟重试或降级 |
OpenAPI 的 info.description 写明「非 2xx 不计费」。402 的具体 code 名称与 200 零命中是否计费，以 OpenAPI 为准。
注意同一个 HTTP 状态码可能对应多个 code：429 就分 RATE_LIMITED 和 DAILY_QUOTA_EXCEEDED，处置完全相反——前者等几秒重试，后者重试只会继续失败。
三、实测样本（无凭证）
2026-10-31 15:04（Asia/Shanghai）对 /subscribe/v1/account 无凭证请求，返回示例：
HTTP/2 401
content-type: application/json; charset=utf-8
cache-control: no-store, max-age=0, no-cache
x-request-id: req_93a5b8a48c413da9
Envelope 中 ok=false、code=UNAUTHORIZED，meta 不含计费字段；meta.request_id 与响应头 X-Request-Id 一致（此前批次实测）。
四、判定函数
# envelope_judge.py —— 示例
RETRY = {"RATE_LIMITED"}
STOP_TODAY = {"DAILY_QUOTA_EXCEEDED"}
STOP_CRED = {"UNAUTHORIZED", "FORBIDDEN_SCOPE"}
def judge(status: int, body: dict) -> str:
code = (body or {}).get("code", "")
if 200 <= status < 300 and body.get("ok"):
return "OK"
if status == 429:
return "RETRY_AFTER" if code in RETRY else "STOP_TODAY"
if status in (401, 403) or code in STOP_CRED:
return "STOP_CREDENTIAL"
if status == 402:
return "STOP_BALANCE"
if status in (400, 404):
return "FIX_PARAMS"
if status in (500, 503):
return "RETRY_ONCE"
return "UNKNOWN" # 记日志，人工看
要点：
- 先看 HTTP 再看
code，避免网关返回非 JSON 时解析崩溃——resp.json()应包 try。 - 2xx 但
ok=false的组合文档未定义，遇到归为UNKNOWN并报警。 - 本地自定义结果加
LOCAL_前缀，不与服务端code混淆。
五、MCP 层的映射
通过远程 MCP（Streamable HTTP）调用时，鉴权失败发生在传输层：tools/list 无凭证返回 HTTP 401、JSON-RPC 错误码 -32001，响应头 WWW-Authenticate 带 resource_metadata。工具调用成功后，工具结果里承载的仍是同一个 Envelope（内容结构以 OpenAPI 为准）。
| 层 | 失败信号 | 用途 |
|---|---|---|
| HTTP 传输 | 401 + WWW-Authenticate |
触发 OAuth 或提示换 Key |
| JSON-RPC | error.code = -32001 |
MCP 客户端识别鉴权失败 |
| 工具结果 | Envelope ok/code |
业务层判定 |
本地代理 127.0.0.1:8787/mcp 只透传，不改写状态码。
六、熔岩数据板块与常见错误码
| 熔岩数据板块 | 代表接口 | 最常见非 OK 码 | 原因解释 |
|---|---|---|---|
| 全市场热榜（个股/概念/加速/首提/加权） | /hot/* |
400 | window、hours、days 超出枚举或范围 |
| 单股多时间窗 | /heat/windows |
404 / 400 | 简称不存在或与 ts_code 同时缺失 |
| 概念板块热度 | /concepts/stocks |
404 / 200 空 | concept 需精确匹配，≤30 字符 |
| 个股消息面记录 | /opinions、/opinions/search |
400 | 区间超 92 天、关键词超 50 字符 |
| 机构/大V评分与覆盖 | /agencies/*、/coverage/stocks |
400 | agency_id 不符合 ^AG[0-9A-F]{12}$ |
| 日频面板 | /panel/daily |
400 | codes 超 20 个或区间超 92 天 |
| 账户 | /account |
401 | Key 失效；本接口不计费 |
七、监测建议
按 code 维度统计每日分布，示例告警线：RATE_LIMITED 占比 > 2%，BAD_REQUEST 单日 > 10 次（说明某个脚本参数漂移），任何 UNAUTHORIZED 立即告警。
FAQ
Q：能只看 ok 不看 HTTP 吗？
A：不建议。网关层错误可能不是 Envelope，先看 HTTP 更稳。
Q：message 能用来判断吗？
A：不能，它面向人阅读，措辞可能调整。
Q：200 且 data 为空列表算失败吗？
A：不算，是零命中；是否计费以 OpenAPI 为准。
结论
HTTP 状态码分大类，Envelope code 定细类，ok 定成败与计费。只重试 RATE_LIMITED 和偶发 5xx，其余按凭证、余额、参数三类直接上报。
数据来自熔岩消息面热度监测，仅用于只读监测与统计研究，不构成投资建议。
只读监测与字段说明见：https://lava.ai-dolphin.com/subscribe/docs
Comments
Join the discussionNo comments yet. Be the first to comment.