GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
全部教程与指南

· reAPI Team

API 500 错误:视频请求何时重试

处理 API 500 错误,避免重复创建付费视频任务。确认提交是否成功、找回任务 ID、限制重试,并安全恢复工作流。

API 500 错误:视频请求何时重试

点了一次,看到错误消息,又点了一次。在视频应用中,这就可能创建两次付费生成,而界面仍显示失败。

设想这样一个请求:服务器接受了第一次提交,启动任务,却在响应返回客户端的途中丢失了响应。客户端收到错误后再次提交。如果端点对每次被接受的提交都会创建一个新任务,两项任务就都可能继续运行。第二次点击没有修复第一次响应,而是又请求生成了一段视频。

这就是 API 500 错误带来的实际难题。AWS 的重试指南提醒,响应失败或超时并不能证明操作没有产生副作用。[1] 重试生成之前,先查明失败请求当时在做什么,以及还有哪些证据能表明它已被接受。

找到失败的请求

“Request failed with status code 500”这样的消息标明的是 HTTP 结果,而不是视频的状态。MDN 将 500 定义为阻止请求完成的意外服务器状况。[2] 它不会告诉你哪个组件发生了故障,也不能证明所有输入都有效,更不保证等待就能解决问题。

查看客户端日志中的方法和 URL。生成 POST 失败,与获取现有任务时失败,后果并不相同。文件下载也可能在前两项操作都成功后失败。如果界面把这三种情况都归为“生成失败”,就会丢失恢复所需的区别。

保留 UTC 时间、模型、状态、响应正文,以及可用的请求或任务标识符。分享日志前先删去凭据。如果响应是 HTML,而不是文档所述的 API 错误格式,也要保留这一事实;不要从通用错误页面中猜测模型故障。

对于假设中的第一次点击,关键问题是你是否有任务 ID。查找服务器保存的提交响应、相关工作流输出,以及任何有文档说明的回调记录。检查实际发送请求的账户或项目。换一个仪表盘账户,并不能确定这次提交是否创建了任务。

有任务 ID 时,从该任务继续

如果找回了标识符,就使用服务商文档规定的读取操作。在 reAPI 上,GET /api/v1/tasks/{id} 可以获取任务,且不会消耗额度。[3] 应通过它继续观察任务;再次发送原来的生成请求正文会创建另一次提交。

读取响应中的任务状态。reAPI 在找到任务时会返回 HTTP 200,即使任务状态为 failed 也是如此。[4] 因此,HTTP 200 并不表示视频已成功。同样,查询返回 500 也不能证明视频失败。这表示查询没有给出可用答案。

对于已完成的任务,应使用文档规定的输出字段处理结果。保存所需文件,不要让应用继续等待第二次生成。处理中的任务应继续观察。对于失败任务,先查看错误和结算信息,再判断是否适合重新尝试。

失败任务与其账单有关联,但两者并不相同。reAPI 说明,失败任务会退款;某些特定模型还可能在生成后进行安全检查,并在已发生可计费生成后拦截输出。[3] 保留该任务实际的用量记录。通用的“服务器错误”提示并不能证明所有费用都应消失;失败生成的计费处理需要结合终态任务及适用政策判断。

没有 ID 时,先保留“是否已接受”这一未决状态

更棘手的情况是第一次点击没有得到可用的提交响应。在应用中,应为该操作明确设置未决状态。例如,内部的 acceptance_unknown 值可以将其与从未发送的工作,以及服务商已确认失败的工作区分开来。这是建议的应用状态,并非每个 API 都会返回的字段。

保留稳定的本地操作 ID,并指定一个恢复负责人。负责人可以核对集成实际提供的证据:保存的响应、回调、获授权查看的任务历史或支持团队的调查结果。如果之后识别出了任务,就将它关联到原操作,并从那里继续。

本地任务 ID 栏为空,只能证明应用没有保存 ID。响应可能是在请求被接受后丢失的。同样,本地操作 ID 不会自动传给服务商,也不会让其创建端点自动去重。它有助于整理证据,但不能证明操作恰好执行了一次。

对于 Idempotency-Key 请求头,也要谨慎。HTTP POST 本身并非幂等操作,重复请求是否安全取决于端点的实际契约。[5] reAPI 明确表示会记录此请求头,但不会用它来对生成请求去重。使用相同的键重复发送已被接受的 POST,仍可能创建另一个任务并产生另一笔费用。[6]

如果证据仍无法得出结论,主动创建替代任务仍可能是业务决策。将它记录为与未决原任务相关联的另一次尝试,并考虑到两项任务都可能完成。不要为了简化重试队列,悄悄把第一次尝试改成“未创建”。那会抹去迟到的结果或费用出现时所需的记录。

检查 n8n 会重复执行什么

在工作流编辑器中,同样的歧义很容易被忽略。标注为“Generate Video”的节点可能会提交任务,然后等待结果。红色节点可能表示等待时间结束,而远端预测任务仍在运行。

WaveSpeed 的官方 n8n 集成文档准确描述了这种行为:生成节点提交预测任务并等待结果。超时值大于零时,节点可能失败,但预测任务仍会继续运行。文档警告,n8n 的 Retry On Fail 会重新运行整个节点,生成一项新的、单独计费的预测任务;瞬时轮询故障已经由内部机制重试。[7] 这一警告适用于该集成,并不自动适用于每个社区节点。

对于由 HTTP Request 节点组成的工作流,检查配置了重试的节点执行什么操作。n8n 说明,Retry on Fail 是节点级设置。[8] 如果该节点发送生成 POST,再尝试一次就会再次发送该 POST。如果它只读取已知任务,重复执行的就是读取操作。工作流显示的错误文本不能代替对节点本身的检查。

一种实用设计是在提交与轮询之间持久化已接受任务的 ID。这样,恢复时就可以从读取步骤继续,而不用再次经过创建步骤。这无法解决上文所述的提交响应丢失问题;应单独保留这条未决路径。手动重新运行整个执行过程也需要同样检查,因为先前已成功的创建步骤可能再次运行。

回到假设中的双击:把第二次点击换成自动节点重试,并没有改变计费问题。应用仍然需要知道自己是在查询原任务,还是在请求生成新任务。

为读取操作设置重试停止点

读取已知任务时发生临时故障,是更适合重试的情况。沿用同一个任务标识,遵守端点文档规定的轮询与速率限制规则,并在允许的尝试次数或经过时间预算耗尽时停止立即重试循环。

AWS 提出了有上限的指数退避、随机抖动和尝试次数限制,以避免持续冲击不稳定的依赖服务。[1] 随机抖动会错开客户端的下一次尝试,而不是让所有尝试都安排在同一时刻。这些技术可以控制重试负载;它们不会让创建用的 POST 变成可去重操作。

指定一个层级负责恢复。如果 SDK、工作流节点和外层工作进程各自独立重试,产生的流量可能超过外层设置所显示的数量。再添加一层循环之前,先检查集成中已有的重试机制。

读取预算用完时,保留任务 ID 以便之后核对。客户端截止时间表示该客户端等待了多久。除非文档规定的取消操作已成功,否则它不能证明远端生成已经停止。应显示检索结果未决状态,而不是提供一个不加说明的“重试”按钮,悄悄提交新的任务。

根据具体错误决定是否创建替代任务

拿到结构化错误后,查看其中的代码及文档规定的适用范围。例如,reAPI 将 60001 和 60002 说明为无法持久化任务或无法启动工作流,并会退还额度。[4] 这些有明确说明的情况,与未知的 HTML 500 响应或提交后连接丢失,支持不同的恢复决策。不要把这些退款处理扩展到所有服务器错误。

如果具体响应指出输入无效或媒体不可用,请先根据该端点的文档修正指出的问题,再提交新的尝试。保留原尝试的证据,并将修正后的提交视为新工作;更改输入不能解决先前是否已被接受这一未决问题。

若没有 HTTP 状态和响应详情,“服务器目前无法处理此请求”同样信息不足。反复修改提示词、刷新浏览器或延长超时时间,都无法确定服务器端故障发生在哪里。对于由服务商管理的端点,应通过其支持流程提供方法、URL、UTC 时间和可用标识符;reAPI 的错误指南规定了这些证据。[4]

如果另一家服务商支持的输入、输出和运行条件适合该任务,它可能是有用的替代方案。但仅仅换了主机名,并不能证明故障路径彼此独立。替代任务成功,也不能确定原提交发生了什么。让两次尝试都保持可见,包括任何之后才完成的原任务。

恢复积压任务前,先核算已经发送的工作。已知任务需要继续观察或记录结果;未知提交需要指定负责人,并明确决定是否替代。第一次重试成功固然有用,但只有当你能说明每个用户请求可能对应哪些远端任务时,恢复过程才清楚可查。

参考资料

  1. AWS Builders Library:超时、重试与带随机抖动的退避。工程指南,最初发表于 2019 年;涉及副作用、有界重试和重试放大。
  2. MDN:HTTP 500 Internal Server Error。定义及服务器端调查。
  3. reAPI Tasks。轮询、状态、输出和结算语义。
  4. reAPI Errors。具体故障代码和支持所需证据。此处的重试决策也依据参考资料 6 中的提交契约。
  5. MDN:幂等。HTTP 方法语义,以及假定重复请求安全的局限。
  6. reAPI API 概览。生成提交和 Idempotency-Key 契约。
  7. WaveSpeed 官方 n8n 集成文档。节点超时、整个节点重试和单独计费的预测任务;检索于 2026 年 11 月 15 日。
  8. n8n 官方 HTTP Request 常见问题文档。Retry on Fail 和节点重试设置;检索于 2026 年 11 月 15 日。
全部教程与指南