# 错误排查

先确认地址、鉴权、模型与余额，再判断是请求错误还是上游异常。

## 按状态码排查

| HTTP 状态 | 优先检查 |
| --- | --- |
| `400` | JSON 格式、必填参数、模型支持的参数范围、参考素材 |
| `401` | API 密钥是否正确、有效，是否带 `Bearer` 请求头 |
| `403` | 密钥权限、来源 IP、模型和分组范围 |
| `404` | 请求路径、模型 ID、任务 ID 及任务归属；是否误填 `/v1/v1` |
| `429` | 请求频率、并发、token 限制或上游限流 |
| `5xx` | 平台或上游服务异常、渠道连接、超时 |

余额不足可能通过不同 HTTP 状态和业务错误码返回，应同时查看响应体。流式请求的错误也可能出现在已经开始的 SSE 中，不能只看最初的 `200`。

## 模型广场有，密钥却不能调用

检查密钥是否选择了正确分组、是否限制了模型范围、是否已过期以及额度是否足够。模型 ID 必须完整匹配；不要使用页面中文别名代替 API ID。

## 一直等不到输出

先检查客户端是否启用了流式，以及客户端、网关或反向代理是否缓冲 SSE。长上下文和推理模型可能有较长首字延迟。设置合理超时，保留请求 ID，不要直接无限重试。

## 参考素材读取失败

检查公网 URL、有效期、下载权限和文件限制。浏览器能打开，不一定代表上游服务可以下载；需要登录的分享页也不等于原始文件链接。

## 视频提交后没有立即返回视频

收到任务 ID 后，按[视频任务](/zh/video/)查询状态。保留最初的任务 ID，在成功后获取结果，不要通过重新生成来“刷新”进度。

## 向客服提供什么

- 发生时间和时区、请求 ID 或订单/任务 ID。
- 调用的模型、接口路径、HTTP 状态与错误码。
- 已脱敏的参数和相关截图。

请勿提供密码、验证码、完整 API 密钥、云服务密钥或仍可访问私有素材的签名链接。