灵眸文档
用户指南

错误码速查

灵眸 API 错误码速查：401 / 403 / 404 / 429 / 5xx 等 HTTP 状态码含义与处理方式，批量生图业务错误码，以及按报错原文反查解决方案。

本页把散落在各接口文档里的错误码汇总成一张速查表。先按 HTTP 状态码定位大类，再按报错原文找到具体解决方案。

排查前先记下请求 ID

响应头中的请求 ID 是定位问题最有效的信息。联系客服时请附上请求 ID 与完整报错文本，不要发送完整 API Key。

HTTP 状态码

状态码典型原因处理方式
400请求体、参数、模型 ID 或模型路径不合法；图片格式 / 编码错误修正请求，不要直接重试——换账号或重试都不会成功
401API Key 缺失、无效、禁用；Base URL 与协议不匹配；IDE 未重启导致旧配置仍生效核对密钥与 Base URL（见接入协议），重启 IDE；详见问题 3
402余额不足充值或减少任务量
403说法有两种，都可能出现：① API Key 所属分组未开启图片生成；② 余额、订阅、计费资格或权限不足先确认账户余额与订阅状态，再确认分组是否具备该能力；两者都正常仍报错则联系客服
404OpenAI 协议地址漏写 /v1、Anthropic 地址多写 /v1、Gemini 未使用 /v1beta/models/...；或该接口不支持当前分组按接入协议重新核对 Base URL 与完整端点
413图生图请求体过大压缩输入图片
429① 当日额度用完；② 并发、RPM 或上游额度受限额度用完见问题 2；限流则指数退避并降低并发与 RPM
500内部或容量错误记录错误码与请求 ID，有限次数重试
502上游认证、权限或服务暂时失败退避重试，必要时联系客服
503无可用上游账号或上游过载；也可能是环境变量覆盖了密钥先排查环境变量（见问题 6），再延迟重试并降低流量
504网关或上游超时作为独立请求重新发起

哪些该重试，哪些必须改请求

  • 不要重试：400、401，以及明确的余额、权限、参数或内容策略错误——请求本身不合法，换任何上游账号都会得到同样的结果，必须先修正请求。
  • 可以重试：429 与 502、503、504，以及网络中断、连接重置和读取超时——都属于暂时性失败。用指数退避做有限次数重试（建议 2～3 次），避免为重复调用付费；429 同时要降低并发与 RPM。

以上分类来自各生图接口的重试建议，详见 Gemini 生图 · 重试建议。

各接口的完整错误说明见：Gemini 生图、GPT 生图、Grok 生图、Gemini 批量生图。

业务错误码（批量生图）

Gemini 批量生图 API 在 HTTP 状态码之外还会返回业务错误码，控制台里显示为 错误码：BATCH_IMAGE_XXX + 请求 ID。

错误码HTTP含义处理
BATCH_IMAGE_DISABLED404全局批量生图未开启将错误码和请求 ID 提供给管理员
BATCH_IMAGE_GROUP_DISABLED403当前 Key 分组未允许批量生图或不是 Gemini 分组更换 Key 或联系管理员开启分组权限
BATCH_IMAGE_NO_ACCOUNT_AVAILABLE502当前没有可用的批量执行资源保存请求 ID 并联系管理员
BATCH_IMAGE_SETTLEMENT_PRICING_MISSING400批量模型没有计费价格联系管理员配置模型价格
BATCH_IMAGE_INVALID_MODEL400未提供模型使用批量模型列表中的模型
BATCH_IMAGE_INVALID_ITEMS400items、分辨率或请求字段不合法检查请求体；当前只支持 1K
BATCH_IMAGE_DUPLICATE_CUSTOM_ID400custom_id 重复确保同一批次内唯一
BATCH_IMAGE_PROMPT_TOO_LONG400提示词过长缩短提示词
BATCH_IMAGE_TOO_MANY_OUTPUT_IMAGES400展开后图片数量超过限制减少 items 或 output_count
BATCH_IMAGE_INVALID_REFERENCE_IMAGE400参考图格式、大小或 URI 不合法检查 MIME、Base64 和 file_uri
BATCH_IMAGE_INSUFFICIENT_BALANCE402余额不足以完成预占充值或减少任务量
BATCH_IMAGE_IDEMPOTENCY_CONFLICT409同一幂等键对应了不同请求体使用新的 Idempotency-Key
BATCH_IMAGE_PROVIDER_SUBMIT_FAILED502上游批任务创建失败保存请求 ID，有限重试或联系管理员
BATCH_IMAGE_QUEUE_FAILED502异步任务服务暂时不可用保存请求 ID 并联系管理员
BATCH_IMAGE_NOT_READY409任务未完成就尝试下载等待状态变为 completed
BATCH_IMAGE_OUTPUT_DELETED410输出已经被清理无法再次下载，需要重新创建任务
BATCH_IMAGE_ITEM_FAILED409指定任务项没有成功图片查看 item.error
BATCH_IMAGE_DOWNLOAD_LIMITED429同时下载数量过多稍后重试

按报错原文查

把你实际看到的报错文本对上下表，直接点进详细解决方案。

报错原文含义详细方案
stream disconnected before completion断流，通常是魔法 / VPN / 系统代理切换出口 IP问题 1
exceeded retry limit, last status: 429 Too Many Requests当日额度已用完问题 2
401 Unauthorized: Incorrect API key provided请求仍走了官方而非灵眸中转问题 3
无法加载文件，因为在此系统上禁止运行脚本（Windows）PowerShell 执行策略限制问题 4
CODEX 无法识别为 cmdlet（Windows）Node.js 未安装或环境变量有问题问题 5
503 No available accountsShell 环境变量覆盖了 IDE 里配置的密钥问题 6
400 Invalid signature in thinking block同一对话内跨分组切换模型，thinking 签名无法验证问题 7
400 Unknown parameter: 'tools[0].n'图像接口误传了 tools 参数问题 8
No available accounts / 模型不可用调用了不在当前分组可用范围内的模型接入协议 → 排错速查

Usage 导出接口的错误

导出 Usage 使用明细 走 JWT 鉴权，错误语义与上面的 API Key 通道不同：

状态码原因处理
401JWT 过期用 refresh_token 续期，或重新登录
403越权（例如查询不属于自己的 api_key_id）检查该 Key 是否属于当前账号
400参数错误（例如 start_date 格式不对）检查 YYYY-MM-DD 格式与 timezone 是否合法

还是没解决？

  • 逐条排查的完整案例见常见问题
  • Base URL / 端点填写规则见接入协议
  • 密钥被盗刷的防护见 Key 安全
  • 联系客服时请附上请求 ID 与完整报错文本

最后更新：

常见问题

灵眸 API 使用过程中常见报错、Token 用量、模型切换、Claude Code / Codex CLI 排障指南与解决方案汇总。

Key 安全

灵眸 API Key IP 白名单 / 黑名单配置指南：限制可调用 IP，防止密钥泄漏被盗刷，支持单 IP 与 CIDR 网段。

On this page

HTTP 状态码业务错误码（批量生图）按报错原文查Usage 导出接口的错误还是没解决？