OpenAI Responses 后台任务长期 queued：轮询、Webhook 与重复事件排查
直接答案
OpenAI Responses 后台任务长期 queued：轮询、Webhook 与重复事件排查
症状、差异与判断依据
先保存 response id 与初始状态
创建后台 Response 后，立即持久化 OpenAI 返回的 response id、创建时间、当前 status、业务幂等键和安全裁剪后的请求摘要。HTTP 2xx 只说明创建请求被接受，不等于模型输出已经完成。 不要只把 id 放在前端内存或某个进程队列里。页面刷新、进程重启或 Worker 切换后，系统必须能从数据库恢复轮询。日志中不要保存完整提示词、输出或 API Key。
queued 与 in_progress 的区别
queued 表示后台响应尚在等待处理，inprogress 表示已经进入处理流程。它们都是非终态。客户端不应在这两个状态读取 outputtext 并把空字符串当成最终答案，也不应因短时间没有变化就创建第二个相同 Response。 为状态机显式定义非终态和终态。终态应按官方 Response 对象当前定义处理，例如 completed、failed、cancelled 或 incomplete；不要只写 status !== completed 就无限重试，因为失败和取消同样需要结束等待并进入相应业务分支。
用 retrieve 做权威回查
保存 response id 后，可调用 retrieve 获取当前 Response。Webhook 是通知通道，retrieve 是恢复丢失通知和核对最终对象的重要手段。若应用在回调处理时崩溃，应使用同一 id 回查，而不是重新生成。 轮询应设置递增间隔、抖动、最长总等待时间和单次请求超时。大量任务固定每秒轮询会制造同步流量尖峰。达到业务等待上限后，可以把任务标记为“待后台确认”，继续低频对账，而不是擅自宣告模型失败。
区分业务超时与 OpenAI 终态
用户界面等待 60 秒超时，只代表当前交互窗口结束，不证明 Response 已失败。后台任务可能随后完成。把 UI timeout、HTTP client timeout、轮询 deadline 和 Response status 分开保存。 若用户离开页面，后台 Worker仍可通过 response id 继续确认状态。最终结果到达后，按产品策略通知用户或在下次访问展示；不要因为前端断开就丢弃权威状态。
取消后台 Response
当业务明确不再需要结果时，可按官方接口对可取消的后台 Response 发起 cancel。取消请求本身也应记录响应对象和状态，不能只在本地把任务改为 cancelled。并发情况下，任务可能在取消到达前已经完成。 采用条件更新：只有数据库当前仍是非终态时才应用取消结果；随后再 retrieve 一次确认最终状态。若完成结果与取消同时到达，按 OpenAI 返回的权威终态和明确业务规则处理，避免一个晚到的本地按钮覆盖真实 completed。
Webhook 只负责通知，不直接代表本地完成
Webhook 事件到达时，先验证签名和事件结构，再使用事件中的对象标识回查或处理。业务系统应以 response id 关联本地任务，并把事件 ID 用于去重。不能只凭 URL 被调用一次就把任务标为 completed。 回调端点应快速返回成功状态。耗时的数据库聚合、通知和内容处理应投入内部可靠队列。处理太慢导致发送方超时，事件可能重试，从而放大重复写入。
必须验证 Webhook 签名
Webhook 端点暴露在公网，任何人都可能构造 HTTP 请求。按照官方 SDK 或文档用 Webhook secret 验证签名，并使用原始请求正文；如果框架先 parse 后重新 stringify，字节变化可能导致验证失败。 签名失败应返回明确的客户端错误并记录脱敏诊断。不要为了排障临时在生产关闭验证，也不要把 secret、完整签名头或原始敏感事件内容写入日志。
重复事件要幂等处理
网络超时和非 2xx 响应可能触发 Webhook 重试，同一个业务结果因而可能被通知多次。为事件 ID建立唯一约束，记录已验证、已入队、处理成功或失败的状态。即使事件 ID 不同，也应通过 (responseid, targetstatus) 或业务版本防止重复发布和重复计费。 处理函数应做到重复执行安全：更新同一行、生成同一通知键、写入同一对象版本。不要用“先查询、再插入”而没有事务或唯一约束，两个并发 Worker 会同时通过查询。
排障步骤与验证
不要依赖事件严格有序
分布式通知可能因重试和网络路径出现延迟。应用不应假设 inprogress 事件总在 completed 之前处理。为状态定义单向优先级或基于权威 Response 的条件更新，终态不应被晚到的非终态覆盖。 收到任何相关事件时，可以 retrieve 当前 Response 并刷新本地投影。若必须高吞吐，至少比较事件创建时间、对象版本和当前状态，并定期对账。
Webhook 与轮询应互为补偿
只轮询会增加请求量并延迟完成感知；只依赖 Webhook 则在配置错误、签名失败或本地停机时可能永久漏状态。可靠架构通常用 Webhook触发快速处理，再由低频对账任务 retrieve 长期停留的 queued/inprogress 项。 当前工作区禁止创建定时任务，因此这里仅记录设计：在获得调度授权前，可由现有合法运行流程或人工触发的恢复命令执行一次性对账，不创建新的 cron 或后台调度。
处理 failed 与 incomplete
failed 表示执行失败，应读取 Response 对象中允许公开的错误信息并映射为内部错误码；incomplete 表示响应未完整完成，需要检查 incomplete details 等官方字段。不要向普通用户展示内部堆栈或完整上游正文。 是否重试取决于失败类型、请求幂等性、成本和业务时效。创建新 Response 会产生新 id 和可能的新输出，必须作为新的尝试记录，不能覆盖原任务历史。
completed 不等于 output_text 必有内容
Response 的输出是结构化 item 集合，可能包含消息、工具调用或其他类型。只读取便捷字段而忽略输出项类型，可能把有效工具调用误报为空。先检查 status，再遍历 output item，并按类型处理。 若业务只接受最终文本，应在契约层明确验证：completed、存在目标 message、内容类型正确、文本非空。验证失败应进入“输出契约不满足”，而不是继续轮询已完成对象。
进程重启后的状态恢复
启动恢复程序时查询本地非终态任务，使用原 response id retrieve。给恢复批次设置并发上限和退避，避免服务重启后数万请求同时涌出。不存在或无权访问的 id 要进入人工诊断队列，不要自动重新生成。 本地任务记录至少包含 OpenAI response id、状态、最后确认时间、下一次允许检查时间、尝试次数和最后安全错误码。任何 Worker 都应能接续，而不依赖原创建进程。
一套逐层排查流程
第一步，确认创建请求确实设置 background，并保存返回 id。第二步，用 retrieve 直接读取当前 Response。第三步，区分非终态、失败、取消、不完整和完成。第四步，核对 Webhook URL、secret 与原始正文签名验证。第五步，检查事件去重和状态单向更新。第六步，检查轮询截止时间与恢复记录。第七步，用同一 id 完成恢复，避免重复创建。 修复后测试 queued→inprogress→completed、failed、incomplete、取消与完成竞态、重复 Webhook、乱序事件、签名失败、回调超时和进程重启。每个场景应只产生一个最终业务结果。
常见错误
常见误区包括：把首次 2xx 当完成；queued 时读取空 outputtext；前端超时后重复创建；Webhook 不验签；回调内同步做重任务；没有事件唯一约束；晚到 inprogress 覆盖 completed；只用 Webhook 没有 retrieve 恢复；以及取消本地状态却不调用或核对上游状态。
总结
Responses API 后台模式的可靠性取决于持久化 response id、明确状态机、Webhook 幂等和 retrieve 补偿。首次 2xx、UI timeout 和回调到达都不是最终业务结论。通过签名验证、重复/乱序保护、取消竞态处理和进程重启恢复，可以在不重复生成的前提下稳定取得每个后台 Response 的唯一最终结果。
常见问题
background 请求返回 queued 是否表示失败？
不表示。queued 是非终态，需要保存 response id，并通过 retrieve 或已验证的 Webhook 等待后续状态。
页面关闭后后台任务还会继续吗？
浏览器页面不是后台 Response 的权威生命周期。应用应持久化 id，并由后端恢复状态；不能依赖前端内存持续轮询。
Webhook 收到两次 completed 怎么办？
按事件 ID去重，并以 response id 和目标状态建立业务幂等约束。重复事件应返回成功但不重复写入、通知或发布。
用户点取消时任务已经完成怎么办？
这是正常竞态。记录 cancel API 的实际响应并 retrieve 权威状态，用条件更新避免晚到的本地取消覆盖已完成结果。
completed 但没有 output_text 是否继续轮询？
不应。completed 已是终态。检查 output item 类型和业务契约；可能是工具调用或目标消息缺失，应作为输出处理问题而不是继续轮询。
官方与规范资料
OpenAI API 错误处理OpenAI 官方文档
Responses API：Create a model responseOpenAI 官方文档