04 // DIAGNOSIS流式 APINVIDIA 独显Apple Silicon Mac阅读与复现约 8 分钟
LLM API 在 HTTP 200 后流式报错：错误发生条件与恢复边界
为什么简单的状态码列表不足以覆盖运行中的失败：深入解析 HTTP 200 响应头发出后的 SSE 流内错误帧、反向代理超时切断与 JSON 截断恢复策略。
[核心实测结论 / TL;DR]在 Tinker AI 实测工坊针对「LLM API 在 HTTP 200 后流式报错：错误发生条件与恢复边界」的复现测试中（实测环境：Node.js 22.13+ 流式客户端 · 适用于 Claude API、OpenAI 兼容接口及本地 Ollama / vLLM，软件版本：Node.js 22.13+ / Anthropic Messages SSE / OpenAI Chat Completions SSE，验证日期：2026-10-23）：为什么简单的状态码列表不足以覆盖运行中的失败：深入解析 HTTP 200 响应头发出后的 SSE 流内错误帧、反向代理超时切断与 JSON 截断恢复策略。 离线边界为「同时适用于本地与云端流式 API」（配套抗中断 SSE 解析器代码，可在本地零成本验证流内异常捕获与超时取消逻辑。），关键限制包括：正如 Claude 官方文档明确指出的：SSE 流式响应一旦发出 HTTP 200 响应头，生成中途发生的过载、OOM 或超时错误已无法修改 HTTP 状态码，只能通过流内 error 事件下发。
REPRODUCIBILITY MANIFEST // 实测环境与边界清单
最后实测验证日期：2026-10-23实测硬件与操作系统 (Tested Hardware & OS)
Node.js 22.13+ 流式客户端 · 适用于 Claude API、OpenAI 兼容接口及本地 Ollama / vLLM
锁定软件与模型版本 (Pinned Stack Versions)
Node.js 22.13+Anthropic Messages SSEOpenAI Chat Completions SSE
离线与外部连接核查 (Offline & Network Boundary)
同时适用于本地与云端流式 API
配套抗中断 SSE 解析器代码，可在本地零成本验证流内异常捕获与超时取消逻辑。
已知限制与失败案例 (Known Limits)
- 正如 Claude 官方文档明确指出的：SSE 流式响应一旦发出 HTTP 200 响应头，生成中途发生的过载、OOM 或超时错误已无法修改 HTTP 状态码，只能通过流内 error 事件下发。
- 当流式响应在生成中途断流时，若对已触发下游写操作的请求无脑重试而未校验幂等键，会导致重复入库或重复发送通知。
遇到环境异常？打开排障诊断树 →
1. 为什么在流式调用中只判断 `if (!res.ok)` 会漏掉严重故障
在传统 REST 接口中，`HTTP 200` 代表请求处理成功。但在 SSE 流式生成中，`HTTP 200` 仅代表在吐出第 1 个 Token 前握手成功。如果生成到第 180 个 Token 时发生显存溢出、上游算力过载或反向代理超时，服务端只能在流内下发一条 `{"error": ...}` 帧并关闭连接。如果客户端只检查了初始状态码，就会把半截残缺文本当成完整回答入库！
表 1：HTTP 200 响应头发出后的四类 SSE 流式故障与客户端恢复边界
| 流式运行期故障类型 | 流内实际报文特征 | 普通客户端错误表现 | 生产级恢复边界动作 |
|---|---|---|---|
| 算力过载 / 显存中途溢出 | 下发 {"error":...} JSON 帧后断连 | 忽略 error 字段，把半截话当成功保存 | 检测 error 字段立即抛错，丢弃残缺缓冲并退避重试 |
| Nginx / 网关 60 秒空闲切断 | 连接直接关闭，无 [DONE] 结束符 | reader.read() 正常结束，误判为完整输出 | 强制校验收到 [DONE] 才允许标记为 completed |
| 触及 max_tokens 长度上限 | finish_reason 为 "length" 且含 [DONE] | 下游 JSON.parse 因缺少闭合括号崩溃 | 解析结构化数据前先断言 finish_reason === "stop" |
| 网络半开连接假死挂起 | 无任何新字节到达，也不关闭连接 | 协程永久挂起，占满连接池 | 为每次分块读取绑定看门狗定时器并主动 cancel |
Three Mandatory Boundaries for Production SSE Readers
// 1. Inspect every SSE JSON frame for mid-stream errors after HTTP 200:
if (event.error || event.type === 'error') {
throw new Error(`Mid-stream SSE error: ${JSON.stringify(event.error || event)}`);
}
// 2. Check finish_reason before JSON.parse:
if (event.choices?.[0]?.finish_reason === 'length') {
throw new Error('Truncated by max_tokens before JSON closed');
}
// 3. Enforce per-chunk idle timeout with reader.cancel()2. 区分“首字预填充等待 (TTFT)”与“生成中途断流”超时
在向本地模型发送万字长文或调用推理模型时，服务端在吐出第 1 个 Token 前的预填充（Prefill）阶段可能保持 30–75 秒静默。工程实现上应采用双阶段超时：首包到达前给予 **60–120 秒首字超时（TTFT Timeout）**，一旦开始流式吐字则切换为 **15 秒分块空闲超时（Chunk Idle Timeout）**。
3. 事务级缓冲提交与流中断后的幂等重试边界
切勿在消费 SSE 分块的半途中边收边写数据库或触发外部 Webhook。正确的恢复边界是：在内存缓冲中累加分块，仅当同时满足 `sawDoneMarker === true` 与 `finishReason === "stop"` 时才一次性提交事务；若中途断流抛错，直接丢弃内存残缺缓冲并携带幂等键安全重试。
FIELD Q&A // 常见实测疑问与边界解答
复现常见疑问与深层原理解答
Q: 官方 SDK 与自己手写 `fetch` 处理 SSE 流有什么区别？
新版官方 SDK 在收到流内 `error` 事件时会抛出异常，但你在 `for await` 循环中已经实时写入数据库或发往前端的半截文本并不会自动回滚。因此涉及结构化入库的操作必须等收到完整结束标志后再提交。
Q: 为什么通过 Nginx 反代流式接口时，经常在整整 60 秒时被掐断连接？
Nginx 默认开启了 `proxy_buffering on` 且 `proxy_read_timeout` 默认为 60 秒。遇到长文本预填充或推理模型思考时极易触发超时断连。请在反代配置中显式设置 `proxy_buffering off; proxy_read_timeout 600s;`。
REPRODUCIBLE ARTIFACT // 配套可参数化附件
sse-stream-guard.mjs ↗抗中断 LLM SSE 流式解析器（捕获 HTTP 200 后的流内报错与截断）
解决“HTTP 状态码为 200 但生成中途断流报错”问题：识别流内 error 事件、空闲超时与长度截断。
修改上方参数将实时更新下方配置内容
// Tinker AI — Resilient SSE Stream Reader with Mid-Stream Error Detection
const API_URL = "http://127.0.0.1:11434/v1/chat/completions";
const IDLE_TIMEOUT_MS = Number("15000");
export async function consumeLlmStream(payload) {
const res = await fetch(API_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ...payload, stream: true }),
});
if (!res.ok || !res.body) {
throw new Error(`Pre-stream HTTP failure: ${res.status}`);
}
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let output = "";
while (true) {
const timer = setTimeout(() => reader.cancel("SSE chunk idle timeout"), IDLE_TIMEOUT_MS);
const { value, done } = await reader.read().finally(() => clearTimeout(timer));
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split("\n");
buffer = lines.pop() ?? "";
for (const raw of lines) {
const line = raw.trim();
if (!line.startsWith("data:")) continue;
const data = line.slice(5).trim();
if (data === "[DONE]") return { output, completed: true };
const event = JSON.parse(data);
// Catch mid-stream error frame sent AFTER HTTP 200 OK
if (event.error || event.type === "error") {
throw new Error(`Mid-stream SSE error after HTTP 200: ${ JSON.stringify(event.error || event) }`);
}
const delta = event.choices?.[0]?.delta?.content ?? "";
output += delta;
}
}
return { output, completed: false };
}