图叮 Image-2 API 失败怎么查：code、errorCode 和 failureReason 别混着看

同一次图叮 Image-2 API 调用里，为什么有人看到 code=10071，有人只在任务详情里看到 status=FAILED，还有人拿到 errorCode=10077？这不是三套互相矛盾的报错，而是调用链上不同节点给出的结果。把它们揉成一个“失败原因”，程序就只能靠猜；把节点拆开，才知道该补积分、改参数、换参考图，还是有限重试。

根据图叮 Image-2 开放平台官方文档，截至 2026 年 7 月，出图采用异步任务：提交请求成功后先返回 taskId，调用方再轮询任务详情。排错也要顺着这条链走。先锁定失败在哪一层，再决定动作。

一个调用至少经过两个失败节点

底层事实很简单：提交接口和生成任务不是同一件事。

提交接口负责检查 API Key、请求格式、参数、能力开关和可用积分。它返回统一的外层信封，核心字段是 code、message、success 和 data。只有 code===200 才表示请求已被接受；这时 data 才是后续要保存的 taskId。HTTP 状态码和 success 都可以辅助观察，但官方合同明确要求以外层 code 为准。

任务节点负责真正生成图片。它有自己的 status：INIT 表示已受理或排队，RUNNING 表示生成中，SUCCESS 表示成功，FAILED 表示失败，VIOLATION 表示内容违规终止。调用方轮询到终态后，再读取 resultUrl、failureReason 或 errorCode。

这两个节点不能互相替代。提交成功只说明“任务进队了”，不说明图片已经生成；任务失败也不等于提交接口当初返回了失败信封。把链路画成最小模型，就是：

请求信封 code → taskId → 任务 status → failureReason / errorCode

图注：先看请求信封，再沿 taskId 追到任务终态。

如果还没把能力参数接稳，可以先看GPT Image 2 能力边界与适用条件。它解决“这项任务是否适合交给模型”，本文解决“接口失败后应该从哪一层读证据”。

外层 code 只回答请求有没有被接受

从前面的事实可以推出第一个结论：拿不到 taskId 时，不要去任务详情里找答案。此时任务很可能根本没有创建，排查入口就是外层 code 和 message。

图叮开放平台官方文档列出的外层错误可以按动作分成几组。100040 指向 API Key 缺失、无效或已吊销；9994 与 100048 多半是参数或枚举不合合同；10071 是 Image-2 积分不足；10073、10074 与高清能力或服务状态有关。2K、4K 传 aspectRatio="auto" 且参考图不可读时，会在扣费前返回 100049，这类问题应改成可访问的公网图片 URL，或显式传支持的宽高比。

重试策略不能只看“失败”两个字。官方错误表把 10072、10076、9999 归到可以有限重试的方向；10071 应先补足积分，9994 应先改参数，100043 表示同一个 Idempotency-Key 被用于不同请求体，需要换键或修正调用逻辑。参数没变就连续重发，只会制造更多噪声。

这里有一条实用判断：外层 code 非 200，先停止轮询；只有拿到非空 taskId，任务状态机才真正开始工作。

任务终态要看 status、errorCode 和 failureReason

第二个结论来自异步模型：拿到 taskId 后，外层 code=200 只证明查询接口正常，不代表生成成功。真正的判断对象已经切换到任务数据里的 status。

官方文档建议轮询间隔为 2～3 秒，直到 SUCCESS、FAILED 或 VIOLATION。SUCCESS 读取 resultUrl；FAILED 优先读取 failureReason，再把 errorCode 当作结构化补充；VIOLATION 是内容违规的独立终态，当前主要对应任务错误码 10077。这里最容易写错的地方，是把任务里的 errorCode 当成外层 code 的镜像。

它们承担的职责不同：

字段	所在层	回答的问题	常见动作
code	请求信封	请求是否被接受	修鉴权、参数、额度或能力条件
status	异步任务	任务仍在运行还是已经终止	继续轮询或进入终态处理
errorCode	异步任务	是否有稳定的结构化失败类型	做程序分支和统计
failureReason	异步任务	本次失败的可读原因是什么	展示原始原因并指导人工排查

多数运行期失败不一定都有稳定的 errorCode，所以 failureReason 不能被丢掉。前端可以把已知错误码翻译成行动建议，但应保留后端原始原因作为兜底。否则一旦出现新渠道、新失败文本或字段缺失，页面只会显示“生成失败”，真正能解决问题的信息反而被抹掉。

把错误分成四类，再决定是否重试

节点分清后，可以把处理逻辑抽成四类，而不是给所有失败统一加一个“重试”按钮。

图注：四类错误对应四种动作，不能统一原样重试。

第一类是输入合同错误。API Key、HTTP 方法、Content-Type、prompt、quality、比例或参考图不合要求时，先修请求。根据官方能力接口，prompt 最大长度、参考图上限和可用比例都应从 /capabilities 获取；当前文档示例里的参考图最多 5 张，2K、4K 的具体比例有明确集合。把这些值写死在旧客户端里，能力变化后就容易出现重复故障。

第二类是账户与能力条件。积分不足、高清未开放、高清服务未就绪，不是网络抖动。程序应把用户带到正确的补充额度或能力确认路径，而不是后台重试十次。图叮网页端当前区分 1K、2K、4K 的积分提示；涉及价格或消耗时要以页面最新显示和账户实际流水为准，不要从旧博客抄固定数字。

第三类是瞬时故障。系统繁忙、操作频繁或泛化系统错误可以有限重试，但需要退避、次数上限和日志。网络层重发还应配合 Idempotency-Key，避免一次用户操作创建多个任务。官方合同规定幂等键最长 128 个字符；同键同请求体可以复用结果，同键不同请求体则会冲突。

第四类是任务内容或生成失败。VIOLATION 不应自动改写提示词后暗中再跑；FAILED 则保留 failureReason，让调用方知道是参考图、生成参数、渠道还是其他原因。若任务已经成功，只是图片出现噪点、文字畸形或边缘伪影，那属于结果质检，不应继续按 API 故障处理。可转到GPT Image 2 高清出图常见问题与修复方法继续排查。

积分、幂等与登录入口是这套判断的边界

一次完整排错还要交叉核对积分流水。图叮开放平台官方文档把 CONSUME 记为负向变动，把失败退款 REFUND 记为正向变动；汇总里的 net 等于 grossConsume-refund。看到任务失败时，不要仅凭余额变化猜是否扣费，按 taskId、消耗记录和退款记录对齐更可靠。

这套推导只适用于图叮 Image-2 开放 API 的响应合同。网页端和 Photoshop 插件有各自的登录态、界面提示与安装流程：官网导航提供登录/注册入口，也提供 Windows 与 macOS 安装教程。网页端弹窗、插件登录失效或安装问题，不能直接套用 API Key 错误码；反过来，开放 API 的 100040 也不等于网页账号密码错误。

边界可以压成一句话：有外层失败就停在请求节点；拿到 taskId 才进入任务节点；任务终态优先读 status 与 failureReason，再用 errorCode 做结构化分支。若产品合同以后新增状态或错误码，应以 /capabilities 和开放平台最新官方文档为准，这篇文章的枚举不能替代实时接口。