Responses API bridge raises APIConnectionError instead of returning truncated response on max_output_tokens

快速结论：该报错发生在 LiteLLM 的 Responses API 桥接模式下，当模型因达到 max_output_tokens 上限而返回空输出时，LiteLLM 错误地将其升级为 APIConnectionError，导致下游调用方收到 HTTP 500。优先升级到 v1.99.0-rc.1 或更高版本，该问题已由 PR #37710 修复。

适用环境：LiteLLM v1.94.3（Issue 确认版本），使用 Responses API 桥接模式（completion_extras.litellm_responses_transformation），受影响模型包括 gpt-5.4-pro 等基于 Responses API 的模型。

最快修复方案：升级 LiteLLM 至 v1.99.0-rc.1 或更高版本。该版本已合并 PR #37710，将不完整响应映射为 finish_reason=”length” 而不是返回 HTTP 500。

注意事项：该修复方案已由 Issue 维护者确认合并，但原始报告者尚未在 v1.99.0-rc.1 上验证。如升级后问题仍复现，需重新打开 Issue。

问题场景

用户在 LiteLLM 中通过 Responses API 桥接模式路由模型（如 gpt-5.4-pro）时触发。当模型在生成任何输出内容前就达到输出令牌上限（max_output_tokens），提供商返回一个包含空输出列表和 incomplete_details.reason=”max_output_tokens” 的 ResponsesAPIResponse。LiteLLM 的转换处理器将此视为致命错误抛出，最终在 /v1/chat/completions 端点表现为不透明的 HTTP 500 错误——而 OpenAI 原生 Chat Completions API 对相同场景（达到令牌上限但未完成）会正常返回 200 响应并携带 finish_reason=”length” 和部分生成的片段。

报错原文

litellm.APIConnectionError: APIConnectionError: OpenAIException - gpt-5.4-pro unable to complete request: max_output_tokens

原因分析

问题出在 LiteLLMResponsesTransformationHandler.transform_response 方法对空输出列表的处理逻辑：当检测到 raw_response.incomplete_details.reason 不为空时，直接抛出 ValueError，而不是将其转换为标准的 finish_reason="length" 响应。这个 ValueError 经过 router.py 的异常映射后变成 litellm.APIConnectionError。如果模型没有配置 fallback 组，该错误就会原样暴露给调用方。这在语义上是不正确的：达到令牌上限是正常生成行为（对应 finish_reason=”length”），而不是 API 连接故障。

环境排查

LiteLLM 版本：确认是否为 v1.94.3 或更早版本（Issue 已确认受影响）；v1.99.0-rc.1 及以上版本已修复。
桥接模式：确认 completion_extras.litellm_responses_transformation 配置是否启用。
模型路由：检查模型是否设置了 fallback 组——有 fallback 时可能掩盖此问题，无 fallback 时直接暴露错误。
响应内容：关注提供商返回的 incomplete_details.reason 字段值是否为 max_output_tokens。

解决步骤

升级 LiteLLM 到 v1.99.0-rc.1 或更高版本（修复已在 PR #37710 中合并）。
升级后，对涉及模型重新发起请求，确认达到 max_output_tokens 上限时返回的是 HTTP 200 且 finish_reason="length"，而非 APIConnectionError。
如果无法立即升级，可优先尝试为模型配置 fallback 组，将 APIConnectionError 路由到备用模型或提供商，避免向最终调用方暴露 HTTP 500。但该方案仅为缓解，不是根因修复。
如果升级后问题仍然复现，请重新打开原始 Issue 并提供复现步骤。

验证方法

升级到 v1.99.0-rc.1 或更高版本后，向使用 Responses API 桥接模式的模型发起一个会触发 max_output_tokens 上限的请求（例如设置较低的最大输出令牌数）。确认响应为 HTTP 200，响应体中的 finish_reason 字段值为 "length"，并且不出现 litellm.APIConnectionError 错误信息。