错误排查
先看 HTTP 状态码,再看正文中的 message 或 error.message。上游可能使用自己的错误格式,具体原因以正文为准。
按状态码排查
| 状态码 | 处理方式 |
|---|---|
400 | 检查 JSON、必填参数、模型类别和接口是否匹配。参数支持范围见 模型页。 |
401 | 检查 Authorization: Bearer <API key>、密钥是否完整或已删除,以及是否来自国内站。 |
402 | 「余额不足」表示余额不够预扣,充值或减少本次用量;余额大于零也可能触发。 |
404 | 检查接口路径和模型 ID;SDK 的 base_url 填到 /v1。视频任务还需确认 ID 和账号归属。 |
429 | 降低请求频率和并发,按正文提示等待后再试。 |
500 | 服务处理异常。保留错误信息,持续出现时联系支持,避免连续重发。 |
502 | 上游暂不可达或调用失败。先确认已有请求或任务状态,再决定是否重试。 |
503 | 服务暂不可用。若正文提示上游服务账户余额或额度不足,可换模型或联系支持,个人充值无法解决。 |
接口和模型类别见 兼容范围。
余额、超时与重复请求
调用前会预扣费用,结算时多退少补,预扣不是最终费用上限。对话可降低输出预算,视频可缩短时长;参数仍需符合模型要求。
客户端超时或断开连接后,上游仍可能继续生成并计费。重试前查看 消费记录。流式对话或语音取得可信用量且计价有效时按实际用量结算;流正常结束或中断后仍无可信用量时退款,语音没有音频产出时也退款。客户端报错不代表已退款。
视频已返回任务 ID 时,使用 GET /v1/videos/{id} 查询原任务。查询失败或仍在生成时,不要重新提交;重复提交会创建新任务。未收到任务 ID 时,先查消费记录,无法确认结果再联系支持。
HTTP 200 但结果异常
- 流式对话:响应开始后无法再修改 HTTP 状态码。中途断开、缺少正常结束标记或收到错误事件时,不能视为完整成功,见 流式响应。
- 普通对话:检查
choices[0].message.content和finish_reason。length表示达到输出上限,思考可能已耗尽预算;按需增加输出预算。 - 语音:检查响应类型、文件是否为空或被截断;错误 JSON 不能当音频播放。
- 视频:提交成功仅表示取得任务 ID,需继续查询任务是否成功,见 多模态接口。
没有收到 HTTP 响应
检查域名、代理、DNS 和 TLS 支持。Gateway 仅接受 TLS 1.3;PowerShell 示例需要 PowerShell 7+、Windows 11 或 Server 2022+,旧环境使用 Python 或 Go 示例。
可用不带密钥的请求检查连通性:
bash
curl --silent --show-error --max-time 15 \
--write-out '\nHTTP %{http_code}\n' \
'https://gw.zeroseal.cn/v1/health'返回 200 和 {"service":"gateway","status":"ok"} 仅说明 HTTP 服务可访问,不验证密钥、余额或模型可用性。证书错误应检查系统时间、证书信任和代理配置,不要关闭证书校验。
联系支持
提供发生时间及时区、模型 ID、接口路径、HTTP 状态码、去除敏感信息后的错误内容和请求 ID(若有);视频问题附任务 ID。删除 Authorization、API key、手机号、请求正文及含访问凭据的媒体链接,不要发送完整调试日志。