错误处理与排查
先分清两层错误：提交/查询的 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 状态；不能只匹配某一条中文错误文本。
常见具体问题
Unknown parameter: 'response_format'：若模型为 gpt-image-2-az 且走 JSON 异步，这是已知兼容问题。仅在客户端删除该字段不能保证解决，因为异步处理会添加它；改用已确认的普通同步路径，并省略 response_format。
模型不存在 / 无权访问 / 无可用渠道：区分拼写、分组权限和实时渠道可用性。先查 /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 或包含凭证的日志。