错误码速查
按状态码定位问题。
错误码速查
收到错误后先记录 HTTP 状态、响应正文和 request id，再判断是请求配置、账户限制还是暂时性上游故障。不要把含凭据的请求头或原始敏感输入发给支持人员。
HTTP 状态码
| 状态码 | 常见原因 | 处理方式 |
|---|---|---|
400 | JSON 结构、模型名称、图片编码或必填字段不正确 | 按对应 API 文档修正请求体；不要原样重复提交 |
401 | Key 未提供、无效或请求采用了错误的鉴权方式 | 检查密钥与请求头，并确认请求发往正确 Base URL |
402 | 账户余额或购买额度不足 | 查看钱包、套餐与使用记录，按页面说明处理 |
403 | Key 停用、IP 规则拦截、模型/分组不匹配或能力未开放 | 检查 Key 状态、来源 IP、模型列表和分组权限 |
404 | URL 路径不匹配或选用的模型/接口当前不可用 | 对照协议页核对 /v1、/v1beta 和资源路径 |
413 | 图片或请求体超过当前端点允许的大小 | 压缩图片，或检查该接口的文件限制 |
429 | Key 限额、速率、并发或上游限流 | 遵循 Retry-After；退避重试并减少并发 |
5xx | 网关或上游暂时异常 | 保存 request id，有限次数退避重试；勿循环高频请求 |
异步图片任务错误
批量图片端点按任务提交后再查询结果。提交成功只表示任务已接收，不代表每个条目都生成成功。查询任务状态和条目详情，并区分“尚未完成”“条目失败”“输出已过期”和“任务被取消”。重试前核对任务 ID 与 custom_id，避免重复生成和重复计费。
按报错原文查
| 报错片段 | 先检查什么 |
|---|---|
stream disconnected / timeout | 网络、代理切换、客户端超时及服务端记录 |
Too Many Requests | Key 限制、并发、Retry-After 和套餐状态 |
Incorrect API key | 密钥有效性、Base URL、旧登录缓存 |
No available accounts | Key 分组和当前模型权限/可用状态 |
API_KEY_REQUIRED | 实际请求是否携带 Authorization 或客户端指定的鉴权头 |
Unknown parameter | 请求是否把不同接口的字段混在一起 |
Invalid signature | 新建会话后重试，避免跨模型复用旧的签名/推理上下文 |
使用记录或控制台接口的错误
控制台“使用记录”需要账户登录，模型网关 API Key 不能替代控制台登录态。遇到 401 时重新登录；遇到 403 时检查记录是否属于当前账户；遇到日期校验错误时确认日期格式和时区。
哪些请求适合重试
连接尚未建立或明确返回临时 5xx 时，可进行有限次数的指数退避重试。验证失败、参数错误、权限不足和余额不足必须先修正原因。图片任务或其他非幂等请求发生超时后，先查询是否已受理，再决定是否创建新任务。