错误、限额与重试
按 HTTP 状态与实际错误排查请求,区分额度和速率限制。
先保存诊断信息
记录请求时间和时区、HTTP 状态、模型 ID、协议、客户端版本和脱敏后的错误内容。响应提供请求标识时一并保留。不要把完整认证头发给支持人员。
先用基础请求复现,再逐项添加可选参数。控制台接口与模型接口的错误格式不同,不能只按某个固定的 error.code 判断所有情况。
按状态排查
状态或现象 | 检查与处理 |
|---|---|
400 | JSON、必填字段、模型参数、上下文和输出限制;修正请求后再试 |
401 | 密钥是否完整、环境变量是否继承、认证头是否匹配协议 |
403 | 密钥或成员状态、模型权限、来源白名单,以及错误中说明的额度问题 |
404 | 主机、版本前缀、端点和模型;检查是否出现重复 |
413 | 请求体或文件过大;按模型要求缩小或拆分 |
429 | 区分调用频率、并发限制和额度限制,按响应提示处理 |
5xx | 网关或模型服务暂时失败;保留请求信息,受控重试或联系支持 |
连接超时或流中断 | 检查网络、代理、客户端超时和流事件;确认服务端是否已执行 |
这些是排查方向,不是所有模型服务共用的错误码契约。余额不足、权限受限等情况的实际状态和消息可能不同。
限额与限流
账户余额、订阅周期额度、成员预算、密钥状态、模型权限、请求频率和并发数分别影响调用。充值不一定解决速率限制,等待也不能解决已用完的预算。固定额度和并发值以当前账户与线路配置为准。
重试策略
可恢复的 429 或服务端临时错误,可采用有次数上限的指数退避并加入随机抖动;响应提供 Retry-After 时遵循该值。400、401、403 等配置或权限错误通常需要先修正原因。
避免同时开启 SDK、业务层和任务队列的多层高频重试。超时后服务端可能已经执行,图片、视频和工具副作用尤其应先查询状态或使用业务去重。收到部分流内容后重试属于新的生成,可能产生额外用量。
持续失败请使用支持模板。