OpenAI Responses API返回incomplete、空output_text或截断：排查指南
直接答案
Responses API请求HTTP成功但响应incomplete、output_text为空、正文被截断或只有reasoning/tool输出时，按status、output items、token预算、拒绝与流式事件定位。
症状、差异与判断依据
直接答案
先记录 HTTP 状态、响应 ID、model、status、incompletedetails、usage、output 中每个 item 的 type/status，以及 message content 的具体类型。若 status=incomplete，按 incomplete reason 处理：输出预算不足时评估并合理提高 maxoutputtokens 或缩短任务；若存在 tool call，执行已授权工具并把结果继续提交；若是 refusal，向用户提供安全解释而非解析成空文本。流式模式必须消费到终止事件并按 item/content delta 组装，不能只读取第一个 chunk。不要记录 API key、完整敏感输入或未经脱敏的模型输出。
一、先区分HTTP成功与生成完成
HTTP 200 表示 API 请求被正常处理并返回 Response 对象，不等于模型一定产出目标文本。业务代码应检查 Response 的 status 和 output 结构，再决定成功、继续工具循环、重试或提示用户。 不要把所有 200 都计为“文章生成成功”。内容流水线还需验证文本非空、结构完整、语言和长度符合要求。
二、保存可关联的响应ID
记录 response ID、请求时间、model、客户端版本和你自己的 trace ID。出现支持问题时，ID 能帮助定位请求；但不得同时输出 API key、Authorization header 或敏感 prompt。 日志应对 input/output 做字段级脱敏，并按数据保留政策处理。只记录 hash 也要注意低熵个人数据可能被反推。
三、读取status而不是猜测
结构化 Response 对象包含 status。应用要显式处理 completed、incomplete、failed、cancelled 等可能状态，而不是只判断是否有 outputtext 属性。 将未知状态视为需要安全处理的新分支，避免 SDK/API 升级后误放行空结果。
四、检查incomplete_details
当响应 incomplete 时，读取 incomplete details 中的原因。不同原因需要不同恢复策略；输出预算不足与安全限制不能用同一种盲目重试处理。 在用户界面显示简洁、无内部敏感信息的说明，内部日志保存稳定错误分类与响应 ID。
五、理解output是Item数组
Responses API 的 output 不只是一个 message 字符串。数组中可能包含 message、reasoning、tool/function call 等 item。代码只读取 output[0].content[0].text 很脆弱：顺序或类型变化就会得到 undefined 或空结果。 应按 type 遍历，并使用官方 SDK 提供的类型定义。对于未知 item，安全忽略并记录类型，不要强制转成文本。
六、output_text是便捷聚合
官方 SDK 可提供 outputtext 便捷属性来聚合文本输出，但它为空时仍需查看原始 output items。它不会把工具调用或 refusal 自动变成普通答案。 业务需要引用、annotations 或分段元数据时，应读取对应 content item，而不是只保留聚合文本。
七、区分output_text与refusal
message content 可以包含文本，也可能包含 refusal 等内容类型。把 refusal 当空字符串会触发无限重试，还会让用户误以为服务故障。 显式识别 refusal，显示合适的安全提示，并允许用户修改请求。不要尝试通过隐藏提示或重复改写绕过安全决策。
八、工具调用不是空答案
模型可能输出 function/tool call，表示需要应用执行工具后继续对话。此时尚未产生最终文本是预期状态。验证工具名称、JSON 参数和授权范围后执行，并将对应结果与正确 call ID 继续提交。 工具执行失败要返回结构化、脱敏错误，不能伪造成功结果。高影响写操作仍需遵守应用的授权与确认策略。
九、reasoning item不是最终文本
推理模型可能在 output 中包含 reasoning 相关 item，但应用不应假设它等同用户可见回答。最终用户内容仍应从 message/text 类型中提取。 不要记录或展示不应暴露的内部推理内容。使用官方提供的 summary/可见字段，并遵守 API 数据处理要求。
十、max_output_tokens限制总输出预算
maxoutputtokens 为响应输出设置上限。预算太低时，模型可能来不及生成完整答案，尤其是需要推理、工具规划或长格式输出的任务。 不要简单设成极大值。根据任务上限、成本、延迟和模型能力配置，并在业务层检查结束标志与文档完整性。
十一、推理也会占用输出预算
对推理模型，输出 token 预算可能同时覆盖可见文本与推理相关 token。复杂问题在生成用户可见文本前已消耗较多预算，就可能出现 incomplete 或很短输出。 可通过简化任务、减少无关上下文、调整适用的 reasoning 配置或合理提高预算来测试。不要把推理 token 误算成丢失文本。
十二、检查usage而非估算
读取 Response usage 中的 input/output token 统计及可用细分，比较正常与失败样本。若输出刚好触及上限且 incomplete，预算是强证据；若输出很少且有 tool call，则应走工具循环。 监控按模型、任务和状态聚合，避免把用户内容作为高基数标签。
十三、上下文窗口与输出预算不同
上下文窗口限制输入与输出合计能力，maxoutputtokens 则是请求指定的输出上限。输入过长可能使请求失败或压缩可用输出空间；输出上限过低则可能 HTTP 成功但生成不完整。 内容系统应分别测量输入和输出，不要只统计全文字符数。
十四、检查prompt是否要求矛盾格式
要求“只返回 JSON”同时又要求 Markdown 解释、极低输出上限和大量章节，会提高截断或格式不完整概率。将硬约束写清优先级，并让 schema/格式与任务规模匹配。 先用最小任务验证调用链，再逐步增加长度。不要把所有要求塞进一个不可验证的超长提示。
排障步骤与验证
十五、结构化输出要验证完整对象
使用结构化输出时，应依据所选 API 功能和 schema 读取结果，并在业务端再次做类型和边界验证。截断的 JSON 不能通过字符串补括号后当作可信结果。 若响应 incomplete，保留原始状态并重新规划任务；不要把部分对象写入生产数据库。
十六、流式响应必须消费到终止事件
流式模式会发送多个事件和 delta。客户端若在首个文本 delta 后关闭连接、超时过短或只监听部分事件，会得到看似截断的文本。 按官方事件类型处理 response/item/content 生命周期，等待终止或错误事件，并在断线时保存已接收状态与 response ID。
十七、不要把SSE行当普通JSON响应
流式传输通常使用 Server-Sent Events。每个事件有自己的类型与 data，不能把整个 HTTP body 一次 JSON.parse，也不能忽略分帧边界。 优先使用官方 SDK 的流式迭代器。自建解析器必须处理多行、心跳、UTF-8 分块和结束事件。
十八、代理可能缓冲或截断流
反向代理、Serverless 网关或企业代理可能缓冲 SSE、设置短 idle timeout、压缩分块或限制响应大小。直连成功而经业务后端失败时，比较两条路径的时间和字节。 调整代理前先核对平台官方限制。不要关闭全站超时或缓冲，应该只对明确流式路由配置。
十九、客户端取消与超时
用户关闭页面、AbortController、应用 deadline 或进程重启都会取消接收。服务端可能已生成部分内容，但客户端没有完整消费。 记录取消来源和时间。只有幂等、安全的任务才可自动重试，并应避免同一文章重复入库。
二十、失败与异常对象要单独处理
网络错误、API 错误响应和 Response 对象内状态不同。SDK 抛异常时保存 HTTP 状态、安全错误码和响应 ID；得到结构化 Response 时按其 status 分支。 不要把所有异常吞掉后返回空字符串。这样会把真实故障误判为模型没有回答。
二十一、重试策略必须分类
瞬时网络或适用的服务端错误可以有限重试；预算不足应改变预算/任务；tool call 应执行工具；refusal 应提示用户；确定性格式错误应先修 prompt/schema。每类都有上限和退避。 使用幂等业务 ID 防止重试产生重复文章、重复写入或重复外部操作。
二十二、长内容应分阶段生成
一次请求生成超长文章更容易触及输出限制、超时或质量漂移。可以先产生经审计的大纲，再按章节生成，最后执行去重、事实检查和一致性合并。 分段时保存明确 checkpoint 和 section ID，避免失败后从头生成导致重复成本与内容。
二十三、完成状态不等于内容合格
completed 只说明 API 生成流程完成，不保证满足业务字数、结构、来源或原创性门禁。内容流水线仍应检查非空、章节数、FAQ、引用、重复标题/slug 和站点主题匹配。 不合格结果应进入修订或人工队列，不能直接发布。
二十四、安全与事实边界
输出可能包含错误或不适当内容。高影响场景应增加人工审查、来源验证和用户输入限制，并避免让不可信文本直接驱动生产操作。 API key 只保存在服务端环境或受管密钥系统。浏览器、日志、文章或错误页面不得包含密钥。
二十五、建立结构化诊断日志
建议记录 responseid、model、status、incompletereason、output item types、文本字符数、usage、流式终止事件、客户端取消原因和业务校验结果。输入输出只存必要的脱敏摘要。 用稳定枚举做指标，监控 incomplete、空文本、工具循环次数和截断率，避免使用完整错误文本作为标签。
二十六、安全恢复步骤
冻结自动发布；保存失败响应摘要；检查 status/incomplete details；遍历 output types；区分 tool/refusal/text；核对 token 预算和 usage；直连测试流式终止；修复提取或代理；用同一小样本回归；再分批恢复生成。 每一步只改一个因素。不要同时升级 SDK、切模型、改 prompt 和提高预算，否则无法确认根因。
二十七、常见错误
常见误区包括：HTTP 200 就当成功；固定读取 output[0]；把 tool call/refusal 当空文本；只依赖 outputtext；incomplete 时原样无限重试；把 maxoutputtokens 设得极低；忽略推理 token；流式只读第一个 chunk；代理提前关闭 SSE；补齐截断 JSON 后写库；记录完整 token 和敏感 prompt。 另一个错误是切换到不同模型后声称已修复。若未比较 status、usage 和 output 结构，问题可能只是暂时隐藏。
二十八、修复后的验收清单
确认所有 Response status 都有分支；incomplete reason 可观测；output 按 type 遍历；message text、refusal、tool call 正确区分；预算符合任务；usage 被记录；流式消费到终止事件；代理不截断；客户端取消可识别；重试分类且有界；业务内容门禁独立；日志无 API key 和敏感全文。 最后用完整文本、tool call、refusal、低 token 预算、客户端取消和流式断线等测试样本验证，确保不会把任何非文本状态误记为合格文章。
总结
Responses API 的成功结果是结构化状态机，不是永远返回一段字符串。可靠排查要联合检查 status、incomplete details、usage、output item/content 类型和流式终止事件，明确区分文本、工具调用、refusal、预算耗尽与客户端中断。修复提取和重试逻辑后，仍需独立内容门禁，才能避免把空结果、截断 JSON 或未完成工具循环误计为合格内容。
常见问题
1. HTTP 200但output_text为空是API故障吗？
不一定。响应可能包含 tool call、refusal 或其他 output item，也可能 incomplete。先检查 status、incomplete details 和完整 output 数组。
2. incomplete可以直接重试吗？
应先读取原因。预算不足需调整任务或 token 上限；工具调用需执行工具；安全结果不应盲目重试。所有重试都应有上限和幂等保护。
3. max_output_tokens越大越好吗？
不是。更大预算可能增加成本和延迟。应按任务规模设置，并通过 usage 与完整性门禁验证，而不是无限放大。
4. 流式文本为什么总在中途停止？
可能客户端未消费终止事件、超时/取消、代理缓冲或连接断开。记录事件序列和取消来源，并用官方 SDK 直连对照。
5. completed响应能直接发布吗？
不能仅凭 completed 发布。还需检查正文、结构、事实、来源、重复和站点匹配，并遵守发布授权与审核规则。
官方与规范资料
OpenAI API 错误处理OpenAI 官方文档
Responses API：Create a model responseOpenAI 官方文档