2026/9/19 19:34:10
FEATURED · 精选文章 
Cherry Studio 流式 API 启动错误改用 HTTP 状态码原理、影响与客户端适配指南【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studiooutput_articleCherry Studio 流式 API 启动错误改用 HTTP 状态码原理、影响与客户端适配指南本篇指南以 Cherry Studiocherry-studio的 breaking-changes 记录 2026-07-16-sse-startup-errors-use-http-status.md 为核心骨架结合仓库内本地 API Gateway 的路由、流代理与错误处理源码及测试用例展开。文章聚焦于一个具体的协议行为变更本地 API Gateway 的流式SSE请求在产生任何模型输出之前发生失败时现在会返回提供商真实的 HTTP 错误状态码4xx/5xx/504而不再像过去那样返回 HTTP 200 并仅在 SSE 错误帧中报告失败。读完本文你将理解该变更的前因后果、底层实现机制启动承诺、状态元数据透传、按方言封装的错误以及如何让自己的自定义 API 客户端同时兼容HTTP 错误响应与流中终止错误事件两种失败形态。一、变更背景从200 SSE 错误帧到真实 HTTP 状态码1.1 变更内容根据 2026-07-16-sse-startup-errors-use-http-status.md 的定义本次变更的要点如下变更对象本地 API Gateway 的流式请求SSEtext/event-stream。变更前流式请求在尚未产生任何模型输出时如果发生失败如上下文长度超限、提供商故障网关会先返回HTTP 200再通过 SSE 错误帧event: error或data: {...}错误帧把失败信息传达给客户端。变更后同样场景下网关直接返回提供商的 HTTP 错误状态4xx、5xx或 504客户端在流开始之前就能从响应状态码识别失败。保持不变一旦流式输出已经开始即服务端已经提交了 HTTP 200 与 SSE 流中途再发生的错误仍然通过 SSE 错误帧上报而不会中途改写 HTTP 状态码——这是 HTTP/SSE 协议本身的约束响应头一旦发出便不可更改。1.2 为什么这对客户端很重要可区分重试语义客户端现在可以在流开始之前区分不可重试的请求错误例如上下文长度溢出context length exceeded属于请求本身的 4xx与可重试的提供商故障5xx、超时从而决定是否自动重试。符合 HTTP 惯例任何没有输出内容的失败本质上是请求没有成功完成返回 4xx/5xx 比返回 200 更符合 HTTP 语义也让标准 HTTP 客户端curl、SDK、代理、日志系统能够按状态码正确归类。客户端需要调整的假设凡是假设流式请求必然以 HTTP 200 开始的客户端都可能在实际请求启动失败时观察到 4xx/5xx/504 响应。这类客户端应补齐对普通 HTTP 错误响应的处理。1.3 变更的依赖前提原文档在 Notes for release manager 中明确指出本变更依赖#17091在 AI SDK 流边界上保留提供商的 status 元数据——即上游错误如AI_APICallError携带的statusCode/status必须穿透到网关的错误处理层否则网关无法获知真实状态码而只能退化为 500。这一点在仓库源码中有直接印证详见下文第三节。二、实现机制源码级解读本次变更的核心实现位于本地 API Gateway 的流代理模块 src/main/features/apiGateway/proxyStream.ts路由入口位于 src/main/features/apiGateway/routes/chat.ts 等文件错误按方言封装位于 src/main/features/apiGateway/errors.ts。2.1 请求流转链路一个流式请求从进入网关到返回客户端经历了以下关键环节路由层Elysia 路由如POST /v1/chat/completions见 chat.ts将请求体、request.signal客户端断开信号与请求头传入processMessage。该函数是整个网关的消息处理中枢接受MessageConfig含inputFormat/outputFormat/streaming/signal等自动从params.stream或路由显式标记判断是否流式见 proxyStream.ts。解析与转换将providerId:modelId形式的外部模型地址解析为内部模型 ID通过MessageConverterFactory把各方言请求体转换为统一的UIMessage组装采样参数、工具、provider 选项等callOverrides。流式分支通过AiStreamManager.streamPrompt发起上游请求one-shot、非持久化的 prompt 流网关作为与 UI 订阅者平级的订阅方监听器把UIMessageChunk经适配器/格式化器翻译成目标方言的 SSE 帧最终返回 Web 标准的Response流式返回text/event-stream的ReadableStream非流式返回 JSON。错误处理启动期失败直接以 HTTP 错误状态拒绝流中期失败通过buildStreamErrorFrame输出方言错误帧。2.2 核心机制启动承诺Startup Commitment这是本次变更的灵魂所在。在 proxyStream.ts 的流式分支中延迟提交 HTTP 响应网关不会立刻返回Response而是先构造一个ReadableStream同时创建一个startupPromise初始状态pending把已生成的 SSE 帧先缓冲到bufferedFrames中等待启动承诺被满足。提交commit的触发条件只有出现有语义的 chunk才提交响应。STARTUP_COMMIT_CHUNK_TYPES定义了这些语义 chunk 类型text-start、text-delta、text-end、reasoning-start、reasoning-delta、reasoning-end、tool-input-available、finish见 proxyStream.ts。注意适配器输出的start帧只是协议脚手架scaffolding不代表提供商已经真正开始产出内容因此不会触发提交。三种结束态committed出现语义 chunk把缓冲帧一次性冲刷给客户端resolveStartup()最终返回 HTTP 200 SSE 流。failed在承诺之前收到onError或onPaused20 分钟空闲超时或中止rejectStartup(error)导致await startup抛出错误进而由路由层/全局onError把错误映射为 HTTP 状态码响应——这就是启动失败返回 HTTP 错误状态的实现路径。abandoned客户端在承诺前断开AbortSignal触发onAbort放弃本次响应并中止上游流。空闲超时网关为流式请求设置了GATEWAY_STREAM_IDLE_TIMEOUT_MS 20 * 60_00020 分钟的 idle 超时见 proxyStream.ts透传给AiStreamManager.streamPrompt。测试用例 src/main/features/apiGateway/tests/proxyStream.stream.test.ts 直接固化了这套行为例如buffers protocol scaffolding until a semantic chunk, then flushes frames done marker验证startchunk 不提交、text-delta才提交响应头为text/event-stream且最终包含data: [DONE]。commits on the semantic %s chunk参数化遍历全部 8 种语义 chunk逐一验证每个语义 chunk 都会触发提交。rejects the original provider error before semantic commitment在startchunk 之后、语义 chunk 之前收到onError({ statusCode: 400 })processMessage的 Promise以原始错误 reject——正是启动失败路径。rejects with a 504 when the stream pauses before semantic commitment承诺前收到onPaused空闲超时/中止以{ status: 504 }拒绝。2.3 状态元数据如何穿透extractError与SerializedError原文档提到的依赖#17091保留 provider status 元数据在错误处理模块中体现为extractError见 errors.ts它从任意抛出的值中尽力提取{ status, message, type }优先读取statusHTTP 库 / OpenAIAPIError其次读取statusCodeAI-SDKAPICallError/SerializedError。SerializedError正是AiStreamManager在onError中序列化出的纯对象形态携带statusCode/message其类型定义见 src/main/ai/streamManager/types.ts。也就是说上游 AI-SDK 错误的statusCode如 400、429、502会一路穿透到网关的错误封装层从而使网关能返回与提供商一致的状态码而不是把所有错误拍平成 500。出于安全考虑extractError有意忽略AI-SDKAPICallError的stack、url、requestBodyValues、responseBody、responseHeaders等敏感字段避免泄漏给客户端见 errors.ts。对应的测试streaming: an error after commitment emits a dialect error frame, not the raw SerializedError断言输出中不包含secret stack、SECRET PROMPT、secret body、https://provider/v1等泄漏内容。三、失败形态的完整矩阵结合 proxyStream.ts 与 errors.ts 的实现流式/非流式请求的失败形态可以归纳如下场景是否已提交产生语义输出客户端看到的响应启动期提供商错误如 400 上下文超长、401、429、5xx否HTTP 4xx / 5xx沿用提供商状态码启动期空闲超时 / 上游中断AiStreamManager归类为paused否HTTP 504流中错误已提交后onError是HTTP 200 SSE 错误帧各方言不同流中空闲超时 / 中断已提交后onPaused是HTTP 200 截断错误帧不是干净的[DONE]客户端在承诺前断开abort否空响应流被放弃不返回错误非流式请求JSON错误—HTTP 4xx / 5xx含 504截断不算 200客户端在非流式请求期间断开—响应作废不强行 504几点细节504 的来源streamInterruptedError()见 proxyStream.ts把流在未完成时暂停空闲超时或中止合成一个status: 504的错误注释明确说明没有这个 504被截断的回复将与真实完成的回复无法区分。非流式路径同样如此onPaused时若客户端未断开则拒绝donePromise 为 504见 proxyStream.ts。流中错误帧 vs 干净的完成已提交后的onPaused走formatPaused输出截断错误帧而不会输出[DONE]测试streaming: a pause after commitment emits a truncation error frame (not a clean [DONE])固化了这一点见 proxyStream.stream.test.ts。3.1 各方言的 SSE 错误帧格式buildStreamErrorFrame见 errors.ts按输出方言生成错误帧与对应 HTTP 错误封装的 message/type 保持一致Anthropic 方言/v1/messagesevent: error{ type: error, error: { type, message, requestId? } }。Gemini 方言/v1beta无命名事件直接data: { error: { code, message, status } }。OpenAI Chat Completions 方言/v1/chat/completions直接data: { error: { message, type, code } }。OpenAI Responses 方言/v1/responsesevent: error{ type: error, code, message }type: error是事件判别符。3.2 按状态码的方言错误映射为了把提供商状态码映射为各方言的错误type/code/ Googlestatus字符串errors.ts 提供了三套映射AnthropicanthropicTypeForStatuserrors.ts401/403 →authentication_error404 →not_found_error429 →rate_limit_error≥500 →api_error其余 →invalid_request_error。OpenAIopenaiTypeAndCodeForStatuserrors.ts401 →authentication_error/invalid_api_key403 →forbidden_error/forbidden404 →not_found_error/not_found429 →rate_limit_error/rate_limit_exceeded≥500 →server_error/internal_error其余 →invalid_request_error/bad_request。GooglegoogleStatusNameerrors.ts400 →INVALID_ARGUMENT401 →UNAUTHENTICATED403 →PERMISSION_DENIED404 →NOT_FOUND429 →RESOURCE_EXHAUSTED500 →INTERNAL503 →UNAVAILABLE504 →DEADLINE_EXCEEDED默认按 ≥500 归为INTERNAL否则INVALID_ARGUMENT。四、作为客户端应如何适配4.1 必做的适配动作原文档明确说明用户侧无需任何操作——该变更是自动生效的但自定义 API 客户端需要同时处理两类失败形态启动期失败 普通 HTTP 错误响应调用流式接口时应先把响应状态码判断为 2xx 再读取流若收到 4xx/5xx/504应解析错误 JSON 体各方言错误封装见上文 3.2 节并按语义决定是否重试——例如 429 可退避重试400 上下文超长一般不可重试5xx/504 可考虑重试。流中期失败 终止性 SSE 错误事件流已经开始后客户端应监听各方言的终止错误帧Anthropic / Responses 的event: errorChat Completions / Gemini 的data:错误帧并识别非[DONE]终止如截断错误帧为失败而非成功完成。4.2 推荐的处理模式伪代码response POST /v1/chat/completions (stream: true, model: providerId:modelId) if response.status ! 200: # 启动期失败4xx/5xx/504按错误封装解析决定是否重试 handleHttpError(response.status, response.body) return # 流式读取 for event in read_sse(response.body): if event is terminal_error_frame(event type / code): mark_failed(event) # 已提交后失败不能当作成功 break if event is [DONE] / finish: mark_succeeded() break process_content(event)4.3 与模型 ID 单冒号变更的联动需要特别提醒本次变更之前的 breaking-change 2026-06-06-api-gateway-model-id-separator.md 已经把网关model字段的解析从双冒号providerId::modelId改为单冒号providerId:modelId按第一个冒号切分模型 ID 本身可含冒号前导/尾随冒号会被以Invalid model format拒绝归类为 400 客户端错误。编写客户端时请使用单冒号形式例如model: openai:gpt-4o。相关解析测试见 src/main/features/apiGateway/tests/proxyStream.parse.test.ts如rejects a leading-colon model、splits on the first colon for a simple provider:model、keeps later colons in the model id。4.4 其他相关边界可参考客户端断开承诺前断开网关会放弃响应并中止上游流返回空响应非流式请求期间断开同样不会强行返回 504。本网关还提供 Cherry REST 方言/knowledge-bases、/models等错误封装{ error: { code, message, details? } }与 MCP JSON-RPC 代理POST /v1/mcps/:id/mcp它们拥有各自独立的错误处理路径restErrorHandler、mcpErrorHandler见 errors.ts本变更只影响流式消息接口。错误处理由全局onError按请求路径自动选择方言dialectForPath见 errors.ts客户端无需额外配置。五、验证方式与可参考的测试如果希望在自己的环境下验证上述行为仓库内的测试是最直接的证据链src/main/features/apiGateway/tests/proxyStream.stream.test.ts覆盖流式路径的启动承诺、提交、错误拒绝400/504、截断帧、abort 行为等。src/main/features/apiGateway/tests/proxyStream.parse.test.ts覆盖模型地址解析与客户端错误400判定。src/main/features/apiGateway/tests/serverShutdown.test.ts覆盖服务生命周期。网关服务端配置端口/主机通过偏好feature.api_gateway.port/feature.api_gateway.host读取见 server.ts并设置了 5 分钟全局请求超时、60 秒 keep-alive 等服务器级参数。动手验证时可以直接向本地网关发送一个构造为启动期失败的流式请求例如请求一个不可用的模型地址、或超出上下文长度的输入观察响应状态码是否为非 2xx再发送一个正常请求中途中断提供商如拔掉网络观察是否为 200 终止错误帧。六、小结本次变更让 Cherry Studio 本地 API Gateway 的流式错误语义回归了 HTTP 的正确姿势输出尚未开始即失败 → 用真实 HTTP 状态码含 504表达输出已开始后的失败 → 用方言 SSE 错误帧表达。其底层由启动承诺 缓冲帧 状态元数据透传三块机制支撑既保证了客户端能区分可重试与不可重试错误也没有牺牲流中错误的表达能力同时通过extractError的字段裁剪避免了内部细节泄漏。对 API 调用方而言核心适配点只有一个不要把流式请求等同于必然 200同时接受HTTP 错误与流内终止错误事件两种失败通道。 /output_article【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio 流式 API 启动错误改用 HTTP 状态码：原理、影响与客户端适配指南
Cherry Studio 流式 API 启动错误改用 HTTP 状态码原理、影响与客户端适配指南【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studiooutput_articleCherry Studio 流式 API 启动错误改用 HTTP 状态码原理、影响与客户端适配指南本篇指南以 Cherry Studiocherry-studio的 breaking-changes 记录 2026-07-16-sse-startup-errors-use-http-status.md 为核心骨架结合仓库内本地 API Gateway 的路由、流代理与错误处理源码及测试用例展开。文章聚焦于一个具体的协议行为变更本地 API Gateway 的流式SSE请求在产生任何模型输出之前发生失败时现在会返回提供商真实的 HTTP 错误状态码4xx/5xx/504而不再像过去那样返回 HTTP 200 并仅在 SSE 错误帧中报告失败。读完本文你将理解该变更的前因后果、底层实现机制启动承诺、状态元数据透传、按方言封装的错误以及如何让自己的自定义 API 客户端同时兼容HTTP 错误响应与流中终止错误事件两种失败形态。一、变更背景从200 SSE 错误帧到真实 HTTP 状态码1.1 变更内容根据 2026-07-16-sse-startup-errors-use-http-status.md 的定义本次变更的要点如下变更对象本地 API Gateway 的流式请求SSEtext/event-stream。变更前流式请求在尚未产生任何模型输出时如果发生失败如上下文长度超限、提供商故障网关会先返回HTTP 200再通过 SSE 错误帧event: error或data: {...}错误帧把失败信息传达给客户端。变更后同样场景下网关直接返回提供商的 HTTP 错误状态4xx、5xx或 504客户端在流开始之前就能从响应状态码识别失败。保持不变一旦流式输出已经开始即服务端已经提交了 HTTP 200 与 SSE 流中途再发生的错误仍然通过 SSE 错误帧上报而不会中途改写 HTTP 状态码——这是 HTTP/SSE 协议本身的约束响应头一旦发出便不可更改。1.2 为什么这对客户端很重要可区分重试语义客户端现在可以在流开始之前区分不可重试的请求错误例如上下文长度溢出context length exceeded属于请求本身的 4xx与可重试的提供商故障5xx、超时从而决定是否自动重试。符合 HTTP 惯例任何没有输出内容的失败本质上是请求没有成功完成返回 4xx/5xx 比返回 200 更符合 HTTP 语义也让标准 HTTP 客户端curl、SDK、代理、日志系统能够按状态码正确归类。客户端需要调整的假设凡是假设流式请求必然以 HTTP 200 开始的客户端都可能在实际请求启动失败时观察到 4xx/5xx/504 响应。这类客户端应补齐对普通 HTTP 错误响应的处理。1.3 变更的依赖前提原文档在 Notes for release manager 中明确指出本变更依赖#17091在 AI SDK 流边界上保留提供商的 status 元数据——即上游错误如AI_APICallError携带的statusCode/status必须穿透到网关的错误处理层否则网关无法获知真实状态码而只能退化为 500。这一点在仓库源码中有直接印证详见下文第三节。二、实现机制源码级解读本次变更的核心实现位于本地 API Gateway 的流代理模块 src/main/features/apiGateway/proxyStream.ts路由入口位于 src/main/features/apiGateway/routes/chat.ts 等文件错误按方言封装位于 src/main/features/apiGateway/errors.ts。2.1 请求流转链路一个流式请求从进入网关到返回客户端经历了以下关键环节路由层Elysia 路由如POST /v1/chat/completions见 chat.ts将请求体、request.signal客户端断开信号与请求头传入processMessage。该函数是整个网关的消息处理中枢接受MessageConfig含inputFormat/outputFormat/streaming/signal等自动从params.stream或路由显式标记判断是否流式见 proxyStream.ts。解析与转换将providerId:modelId形式的外部模型地址解析为内部模型 ID通过MessageConverterFactory把各方言请求体转换为统一的UIMessage组装采样参数、工具、provider 选项等callOverrides。流式分支通过AiStreamManager.streamPrompt发起上游请求one-shot、非持久化的 prompt 流网关作为与 UI 订阅者平级的订阅方监听器把UIMessageChunk经适配器/格式化器翻译成目标方言的 SSE 帧最终返回 Web 标准的Response流式返回text/event-stream的ReadableStream非流式返回 JSON。错误处理启动期失败直接以 HTTP 错误状态拒绝流中期失败通过buildStreamErrorFrame输出方言错误帧。2.2 核心机制启动承诺Startup Commitment这是本次变更的灵魂所在。在 proxyStream.ts 的流式分支中延迟提交 HTTP 响应网关不会立刻返回Response而是先构造一个ReadableStream同时创建一个startupPromise初始状态pending把已生成的 SSE 帧先缓冲到bufferedFrames中等待启动承诺被满足。提交commit的触发条件只有出现有语义的 chunk才提交响应。STARTUP_COMMIT_CHUNK_TYPES定义了这些语义 chunk 类型text-start、text-delta、text-end、reasoning-start、reasoning-delta、reasoning-end、tool-input-available、finish见 proxyStream.ts。注意适配器输出的start帧只是协议脚手架scaffolding不代表提供商已经真正开始产出内容因此不会触发提交。三种结束态committed出现语义 chunk把缓冲帧一次性冲刷给客户端resolveStartup()最终返回 HTTP 200 SSE 流。failed在承诺之前收到onError或onPaused20 分钟空闲超时或中止rejectStartup(error)导致await startup抛出错误进而由路由层/全局onError把错误映射为 HTTP 状态码响应——这就是启动失败返回 HTTP 错误状态的实现路径。abandoned客户端在承诺前断开AbortSignal触发onAbort放弃本次响应并中止上游流。空闲超时网关为流式请求设置了GATEWAY_STREAM_IDLE_TIMEOUT_MS 20 * 60_00020 分钟的 idle 超时见 proxyStream.ts透传给AiStreamManager.streamPrompt。测试用例 src/main/features/apiGateway/tests/proxyStream.stream.test.ts 直接固化了这套行为例如buffers protocol scaffolding until a semantic chunk, then flushes frames done marker验证startchunk 不提交、text-delta才提交响应头为text/event-stream且最终包含data: [DONE]。commits on the semantic %s chunk参数化遍历全部 8 种语义 chunk逐一验证每个语义 chunk 都会触发提交。rejects the original provider error before semantic commitment在startchunk 之后、语义 chunk 之前收到onError({ statusCode: 400 })processMessage的 Promise以原始错误 reject——正是启动失败路径。rejects with a 504 when the stream pauses before semantic commitment承诺前收到onPaused空闲超时/中止以{ status: 504 }拒绝。2.3 状态元数据如何穿透extractError与SerializedError原文档提到的依赖#17091保留 provider status 元数据在错误处理模块中体现为extractError见 errors.ts它从任意抛出的值中尽力提取{ status, message, type }优先读取statusHTTP 库 / OpenAIAPIError其次读取statusCodeAI-SDKAPICallError/SerializedError。SerializedError正是AiStreamManager在onError中序列化出的纯对象形态携带statusCode/message其类型定义见 src/main/ai/streamManager/types.ts。也就是说上游 AI-SDK 错误的statusCode如 400、429、502会一路穿透到网关的错误封装层从而使网关能返回与提供商一致的状态码而不是把所有错误拍平成 500。出于安全考虑extractError有意忽略AI-SDKAPICallError的stack、url、requestBodyValues、responseBody、responseHeaders等敏感字段避免泄漏给客户端见 errors.ts。对应的测试streaming: an error after commitment emits a dialect error frame, not the raw SerializedError断言输出中不包含secret stack、SECRET PROMPT、secret body、https://provider/v1等泄漏内容。三、失败形态的完整矩阵结合 proxyStream.ts 与 errors.ts 的实现流式/非流式请求的失败形态可以归纳如下场景是否已提交产生语义输出客户端看到的响应启动期提供商错误如 400 上下文超长、401、429、5xx否HTTP 4xx / 5xx沿用提供商状态码启动期空闲超时 / 上游中断AiStreamManager归类为paused否HTTP 504流中错误已提交后onError是HTTP 200 SSE 错误帧各方言不同流中空闲超时 / 中断已提交后onPaused是HTTP 200 截断错误帧不是干净的[DONE]客户端在承诺前断开abort否空响应流被放弃不返回错误非流式请求JSON错误—HTTP 4xx / 5xx含 504截断不算 200客户端在非流式请求期间断开—响应作废不强行 504几点细节504 的来源streamInterruptedError()见 proxyStream.ts把流在未完成时暂停空闲超时或中止合成一个status: 504的错误注释明确说明没有这个 504被截断的回复将与真实完成的回复无法区分。非流式路径同样如此onPaused时若客户端未断开则拒绝donePromise 为 504见 proxyStream.ts。流中错误帧 vs 干净的完成已提交后的onPaused走formatPaused输出截断错误帧而不会输出[DONE]测试streaming: a pause after commitment emits a truncation error frame (not a clean [DONE])固化了这一点见 proxyStream.stream.test.ts。3.1 各方言的 SSE 错误帧格式buildStreamErrorFrame见 errors.ts按输出方言生成错误帧与对应 HTTP 错误封装的 message/type 保持一致Anthropic 方言/v1/messagesevent: error{ type: error, error: { type, message, requestId? } }。Gemini 方言/v1beta无命名事件直接data: { error: { code, message, status } }。OpenAI Chat Completions 方言/v1/chat/completions直接data: { error: { message, type, code } }。OpenAI Responses 方言/v1/responsesevent: error{ type: error, code, message }type: error是事件判别符。3.2 按状态码的方言错误映射为了把提供商状态码映射为各方言的错误type/code/ Googlestatus字符串errors.ts 提供了三套映射AnthropicanthropicTypeForStatuserrors.ts401/403 →authentication_error404 →not_found_error429 →rate_limit_error≥500 →api_error其余 →invalid_request_error。OpenAIopenaiTypeAndCodeForStatuserrors.ts401 →authentication_error/invalid_api_key403 →forbidden_error/forbidden404 →not_found_error/not_found429 →rate_limit_error/rate_limit_exceeded≥500 →server_error/internal_error其余 →invalid_request_error/bad_request。GooglegoogleStatusNameerrors.ts400 →INVALID_ARGUMENT401 →UNAUTHENTICATED403 →PERMISSION_DENIED404 →NOT_FOUND429 →RESOURCE_EXHAUSTED500 →INTERNAL503 →UNAVAILABLE504 →DEADLINE_EXCEEDED默认按 ≥500 归为INTERNAL否则INVALID_ARGUMENT。四、作为客户端应如何适配4.1 必做的适配动作原文档明确说明用户侧无需任何操作——该变更是自动生效的但自定义 API 客户端需要同时处理两类失败形态启动期失败 普通 HTTP 错误响应调用流式接口时应先把响应状态码判断为 2xx 再读取流若收到 4xx/5xx/504应解析错误 JSON 体各方言错误封装见上文 3.2 节并按语义决定是否重试——例如 429 可退避重试400 上下文超长一般不可重试5xx/504 可考虑重试。流中期失败 终止性 SSE 错误事件流已经开始后客户端应监听各方言的终止错误帧Anthropic / Responses 的event: errorChat Completions / Gemini 的data:错误帧并识别非[DONE]终止如截断错误帧为失败而非成功完成。4.2 推荐的处理模式伪代码response POST /v1/chat/completions (stream: true, model: providerId:modelId) if response.status ! 200: # 启动期失败4xx/5xx/504按错误封装解析决定是否重试 handleHttpError(response.status, response.body) return # 流式读取 for event in read_sse(response.body): if event is terminal_error_frame(event type / code): mark_failed(event) # 已提交后失败不能当作成功 break if event is [DONE] / finish: mark_succeeded() break process_content(event)4.3 与模型 ID 单冒号变更的联动需要特别提醒本次变更之前的 breaking-change 2026-06-06-api-gateway-model-id-separator.md 已经把网关model字段的解析从双冒号providerId::modelId改为单冒号providerId:modelId按第一个冒号切分模型 ID 本身可含冒号前导/尾随冒号会被以Invalid model format拒绝归类为 400 客户端错误。编写客户端时请使用单冒号形式例如model: openai:gpt-4o。相关解析测试见 src/main/features/apiGateway/tests/proxyStream.parse.test.ts如rejects a leading-colon model、splits on the first colon for a simple provider:model、keeps later colons in the model id。4.4 其他相关边界可参考客户端断开承诺前断开网关会放弃响应并中止上游流返回空响应非流式请求期间断开同样不会强行返回 504。本网关还提供 Cherry REST 方言/knowledge-bases、/models等错误封装{ error: { code, message, details? } }与 MCP JSON-RPC 代理POST /v1/mcps/:id/mcp它们拥有各自独立的错误处理路径restErrorHandler、mcpErrorHandler见 errors.ts本变更只影响流式消息接口。错误处理由全局onError按请求路径自动选择方言dialectForPath见 errors.ts客户端无需额外配置。五、验证方式与可参考的测试如果希望在自己的环境下验证上述行为仓库内的测试是最直接的证据链src/main/features/apiGateway/tests/proxyStream.stream.test.ts覆盖流式路径的启动承诺、提交、错误拒绝400/504、截断帧、abort 行为等。src/main/features/apiGateway/tests/proxyStream.parse.test.ts覆盖模型地址解析与客户端错误400判定。src/main/features/apiGateway/tests/serverShutdown.test.ts覆盖服务生命周期。网关服务端配置端口/主机通过偏好feature.api_gateway.port/feature.api_gateway.host读取见 server.ts并设置了 5 分钟全局请求超时、60 秒 keep-alive 等服务器级参数。动手验证时可以直接向本地网关发送一个构造为启动期失败的流式请求例如请求一个不可用的模型地址、或超出上下文长度的输入观察响应状态码是否为非 2xx再发送一个正常请求中途中断提供商如拔掉网络观察是否为 200 终止错误帧。六、小结本次变更让 Cherry Studio 本地 API Gateway 的流式错误语义回归了 HTTP 的正确姿势输出尚未开始即失败 → 用真实 HTTP 状态码含 504表达输出已开始后的失败 → 用方言 SSE 错误帧表达。其底层由启动承诺 缓冲帧 状态元数据透传三块机制支撑既保证了客户端能区分可重试与不可重试错误也没有牺牲流中错误的表达能力同时通过extractError的字段裁剪避免了内部细节泄漏。对 API 调用方而言核心适配点只有一个不要把流式请求等同于必然 200同时接受HTTP 错误与流内终止错误事件两种失败通道。 /output_article【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
