跳到主要内容

错误修复

按错误现象和 HTTP 状态码定位原因，先完成最小验证，再逐步恢复请求。

401 未认证​

  • 现象： 请求通常会返回 401 未认证，客户端可能只显示“请求失败”或一段简短错误。
  • 原因： Key 缺失、失效、复制不完整，或认证请求头不符合当前协议。
  • 自查：
    1. 确认请求中确实有认证请求头，且没有把 YOUR_API_KEY 留在示例值。
    2. 从密钥页重新复制 Key，检查前后空格、换行和是否已停用。
    3. 按协议核对 Authorization: Bearer、x-api-key 或 x-goog-api-key。
  • 处理： 重新从密钥页复制 Key，去掉首尾空格，并核对 Bearer、x-api-key 或 x-goog-api-key。
  • 验证： 修复后只发送一条短文本请求；收到正常 JSON 和内容后，再恢复原来的参数与任务。

403 无权限​

  • 现象： 请求通常会返回 403 无权限，客户端可能只显示“请求失败”或一段简短错误。
  • 原因： 当前 Key、账户状态或模型访问范围不允许这次请求。
  • 自查：
    1. 在主站确认账户状态正常，当前 Key 没有被停用或限制。
    2. 从模型与价格页重新选择一个当前可用模型，确认 Key 的分组覆盖它。
    3. 不要用不断重试来绕过权限限制；先修正 Key 或模型范围。
  • 处理： 确认 Key 仍可用，并在模型与价格页重新选择当前可访问的模型。
  • 验证： 修复后只发送一条短文本请求；收到正常 JSON 和内容后，再恢复原来的参数与任务。

404 未找到​

  • 现象： 请求通常会返回 404 未找到，客户端可能只显示“请求失败”或一段简短错误。
  • 原因： Base URL、协议路径或 HTTP 方法不匹配，客户端也可能重复追加 /v1。
  • 自查：
    1. 把实际请求 URL 复制出来，检查是否出现 /v1/v1、路径拼写错误或把 POST 写成 GET。
    2. OpenAI compatible 客户端通常填 https://api.popgo.site/v1，不要再手动追加 /chat/completions。
    3. 对照协议页逐段比较 Base URL、接口路径和 HTTP 方法。
  • 处理： 对照协议页检查完整路径和方法；Base URL 只填写教程指定层级。
  • 验证： 修复后只发送一条短文本请求；收到正常 JSON 和内容后，再恢复原来的参数与任务。

429 请求过多​

  • 现象： 请求通常会返回 429 请求过多，客户端可能只显示“请求失败”或一段简短错误。
  • 原因： 短时间请求过密，或当前可用额度不足。
  • 自查：
    1. 确认是不是同时打开了多个客户端或脚本，先暂停重复任务并降低并发。
    2. 检查主站额度和 Key 限制；额度不足时等待或更换有额度的 Key。
    3. 重试时使用递增等待，不要在循环中立即连续发送。
  • 处理： 降低并发，按递增间隔重试，并在主站确认账户状态后再继续。
  • 验证： 修复后只发送一条短文本请求；收到正常 JSON 和内容后，再恢复原来的参数与任务。

5xx 服务错误​

  • 现象： 请求通常会返回 5xx 服务错误，客户端可能只显示“请求失败”或一段简短错误。
  • 原因： 上游或网关暂时无法完成请求。
  • 自查：
    1. 保存响应中的 request ID（如有）、时间和状态码，不要只截图客户端提示。
    2. 用同一 Key 和模型重跑最小 curl，判断是客户端配置还是服务暂时异常。
    3. 连续失败时暂停批量任务，稍后再验证，避免放大请求量。
  • 处理： 保留请求时间和状态码，稍后重试；连续失败时先用 curl 最小请求排除客户端配置。
  • 验证： 修复后只发送一条短文本请求；收到正常 JSON 和内容后，再恢复原来的参数与任务。

网络中断​

  • 现象： 请求通常会返回 网络中断，客户端可能只显示“请求失败”或一段简短错误。
  • 原因： 本地网络、代理或长连接在响应完成前断开。
  • 自查：
    1. 先确认域名可以访问，再观察是 DNS、TLS、代理还是长连接中断。
    2. 用 curl -I https://api.popgo.site 检查基础网络，不要把网络错误误判成模型错误。
    3. 流式请求断开时再连接；非幂等操作不要盲目重复提交。
  • 处理： 确认域名可访问；流式请求使用退避重连，非幂等操作不要自动重复提交。
  • 验证： 修复后只发送一条短文本请求；收到正常 JSON 和内容后，再恢复原来的参数与任务。

推荐排查顺序​

  1. 先记录完整错误：HTTP 状态码、请求路径、客户端名称和发生时间。
  2. 用快速开始页的最小 curl 请求复现，确认问题来自 Key、模型、地址还是客户端。
  3. 一次只改一个变量；修复后先验证短文本请求，再恢复流式、工具调用或媒体参数。

仍未恢复​

保留发生时间、协议、HTTP 方法、路径、状态码和已脱敏的响应片段。不要附上完整 Key。

视频生成故障定位​

先判断错误发生在提交前、PopGo解析、服务接受、轮询还是下载。保留具体错误短语，不要只依据500或“上游没有记录”归因。

阶段处理
first-frame requires exactly one / first-last-frame requires both先选素材模式，确认首帧一张或两个不同槽位；检查节点输入连线和实际参考数量
reference-audio requires at least one / audio not supported确认当前能力支持音频、允许挂载到所选模式，并提供音频；generate_audio不授予参考权限
unsupported protocol: data / invalid sourceURL-only型号使用允许的公网URL；本地标签不会自动转换公网
任务长期0% / completed但下载失败查询原id，给内容准备时间；不要通过重复创建消除等待
生成成功但忽略素材检查字段和可访问性，再看成片；不能只以HTTP200验收

公开HTTP 400通常表示请求需要修正，500也可能来自本地解析或中间层；503常见于容量暂不可用。先检查脱敏错误细节。完整的视频任务排错流程包含轮询、费用和证据边界。