错误修复

按错误现象和 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 和内容后，再恢复原来的参数与任务。

仍未恢复

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

视频排错

先记录 HTTP 状态、错误码和简短错误消息，再按下表处理。字段与限制见视频模型参数，调用顺序见视频任务流程。

现象	检查与处理
HTTP 400 / 参数错误	按模型检查必填字段、类型、时长、分辨率、比例、素材数量和角色。修正请求后再提交。
HTTP 401 / 403	检查 Authorization: Bearer YOUR_API_KEY、Key 状态、模型权限和账户额度。不要将 Key 放入 URL 参数。
HTTP 404	检查方法和完整路径，避免重复拼接 /v1。查询与下载使用本次返回的任务 ID 和有权访问它的 Key。
HTTP 429	降低并发，遵守 Retry-After，采用有上限的退避，并核对额度。创建结果不明时，按下方超时说明处理。
HTTP 502 / 503 或网络错误	查询与下载可对同一任务有限重试。创建结果不明时，按下方超时说明处理，避免重复创建。
素材无法读取 / 403 / 过期	使用可公开下载且有效至生成完成的 HTTPS 直链，核对公网访问、实际格式、大小与时长；浏览器可预览不代表服务端可下载。
长时间 queued / in_progress 或 progress 为 0	保留 ID，延长客户端等待并继续有限轮询。进度可能缺失或最后才更新，不要重复创建。
completed 但下载失败	检查同一任务的 /content、HTTP 状态和 Content-Type。内容暂不可用时有限重试并及时保存；不要把 JSON 错误存成 MP4。
参考效果不符	检查实际发送的素材字段、数量、顺序和角色。普通参考图与首尾帧不同，先对比下载结果再决定是否重建。

创建超时与重复请求

已收到 id 时，继续查询原任务。未收到 id 时，先不要重试；保留响应头 X-Oneapi-Request-Id（如已收到）、请求时间和模型名，联系平台查询。当前无法通过请求编号自助找回任务。重新创建可能产生新的计费任务；自行发送 idempotency_key 不能保证接口去重。

向支持人员提供什么

提供模型名、时间与时区、HTTP 状态、错误码、请求格式、非敏感参数及素材类型和数量。任务 ID 或请求 ID 请私下向支持人员提供。公开示例使用 YOUR_TASK_ID、YOUR_IMAGE_URL 等占位符；删除 API Key、Authorization 头、Cookie、签名链接及私人素材。失败或超时是否收费，以主站用量和账单为准。

401 未认证​

403 无权限​

404 未找到​

429 请求过多​

5xx 服务错误​

网络中断​

推荐排查顺序​

仍未恢复​