错误处理与排查
先分清两层错误：提交/查询的 HTTP 错误，以及 HTTP 200 查询结果里的失败任务。两者都要检查。
HTTP 状态速查
| 状态/现象 | 常见原因 | 正确处理 |
|---|---|---|
| 400 | 字段、尺寸、MIME 或模型参数不匹配 | 按 error.message 修正；不要原样循环重试 |
| 401 | Key 缺失、无效、过期 | 检查 Bearer 格式、令牌状态与有效期 |
| 403 或权限相关错误 | 分组/模型权限或令牌限制 | 对照 Key 的分组与 /v1/models |
| 余额/额度不足 | 账户余额或令牌额度不足 | 核对钱包及令牌额度；不要只按固定 HTTP 402 判断 |
| 404 查询图片任务 | ID 错误、Key 不同、任务清理 | 使用原 Key 与推荐查询路径，核对任务时间 |
| 413 | 上传体积超过入口限制 | 缩小图片/请求；Base64 会增加传输体积 |
| 429 | 速率、并发、队列或资源限制 | GET 按 Retry-After 退避；提交结果不明时不要自动重发 |
| 500/502/503/504 | 服务暂时异常 | 有 task_id 则继续核对该任务；无 ID 则先查记录 |
| HTTP 200 但 status=failed | 任务执行失败 | 读取 error.message，停止正常轮询 |
| HTTP 200/completed 但没有图片 | 空结果、格式不兼容或生成异常 | 视为业务失败，保存 ID 与响应摘要反馈 |
| 浏览器 CORS 报错 | 第三方网页直接跨域访问 | 改为从自己的后端调用，不在前端暴露 Key |
不同模型和渠道的错误封装可能不同。通用读取顺序为 error.message、message，并保留 HTTP 状态；不能只匹配某一条中文错误文本。
常见具体问题
参数不支持：按当前完整型号删除不支持的字段。Mini/Fast 不接收 1080p/4K，SD-2.0-MZ1 不支持关闭音频或参考视频，H3 不使用 generate_audio 开关。不能把另一型号的请求原样复制过来。
模型不存在 / 无权访问 / 无可用渠道：区分拼写、分组权限和实时渠道可用性。先查 /v1/models，再查模型状态页。目录列出模型不代表某时刻一定有可用容量。
拿到 task_id 但客户端一直转圈：检查是否只识别 succeeded 而漏掉 completed，是否只读取 result 而忽略 data，以及是否把毫秒误当成秒。未知状态和 GET 错误必须有截止时间。
返回图片不是请求的像素尺寸：size 是请求目标，有些渠道会归一、取整或使用固定档位。应读取原图像素，不能仅用响应回显的 size 判断规格兑现。
账单看起来重复：检查客户端/SDK/反向代理是否自动重试 POST，以及超时后是否手动再次提交。同一个 Idempotency-Key 当前也不能保证去重。
反馈时提供什么
text
接口路径：
请求时间与时区：
模型完整 ID：
分组名称：
HTTP 状态：
task_id：
request_id（若有）：
error.message：
是否曾重复提交：
脱敏后的必要参数（不包含完整图片 Base64）：
排查时提供以上脱敏信息。不要发送完整 Key、Cookie、未脱敏 Authorization 或包含凭证的日志。
视频特有错误
素材上传的 415/422 检查 MIME、编码、时长与像素；视频 /content 的 400 先查任务是否完成，410 检查资源是否失效。下载失败只重试原任务下载，不能重新生成。完整对照见视频任务与下载和素材上传。
新图片与工具请求的常见问题
| 错误/现象 | 检查与处理 |
|---|---|
| prompt is required / non-empty string | 顶层prompt类型、Content-Type与body一致性、多层转发是否丢字段；见参考图 |
| MJ size不支持 | 使用比例枚举，不传像素或4K；quality用数值 |
| Adobe中质量尺寸失败 | 本组已支持明确4K；检查是否超出长边4096/4K范围，参考GPT图片章节 |
| Seedream Pro请求4k | 选Lite 4k，Pro只使用1k/2k |
| 返回5张但只看见1张 | 遍历全部data[]，完整客户端下载全部图片 |
| AS Gemini视频HTTP200但理解错误 | 使用已验证的原生MP4 inlineData，不用状态码替代内容检查 |
| 工具调用后不回答 | 回传role=tool、正确tool_call_id并保留完整assistant消息 |
| 页面关闭后仍有消费 | 合法生成可能继续完成并结算，查原任务和图库，不重复生成 |