Midjourney API 常见报错与任务失败排查：401、429、超时（2026）

搜“Midjourney API 报错”的开发者，通常找不到官方错误码表。Midjourney 没有面向公众的通用 API，你调用的大多是第三方封装或中转网关，状态码、错误字段和重试规则由服务商定义。同一个 401，在两家平台可能对应不同原因。

本文按 HTTP 语义和任务生命周期归类常见故障，给出排查顺序、重试与幂等写法，以及工单清单。接口、错误码和计费以服务商文档为准。

说明：Midjourney 是 Midjourney, Inc. 的商标；Discord 是 Discord Inc. 的商标。本文讨论的第三方封装与中转服务与上述公司无隶属关系，接口、错误码与计费以服务商文档为准。

一、先定位错误发生在哪一层

一次调用经过五层：客户端与网络、网关鉴权、上游账号池、生成任务、结果存储与 CDN。不同层故障表现不同：

症状	可能所在层	第一步
所有接口都失败	客户端、网络、DNS、代理	换网络或用最小请求复现
只有 Midjourney 失败	通道或上游账号池	查服务商状态页与其他模型
提交阶段返回 4xx	鉴权、参数、限流	对照错误码检查请求
提交成功但任务失败	生成、审核、上游账号	读任务错误字段
任务成功但图片打不开	结果链接、CDN、下载	查链接有效期并重试下载

排查时先回答三个问题：是全部失败还是个别失败？是提交失败还是任务失败？是固定复现还是高峰期出现？这三个答案能把范围缩小一半。

二、401 与 403：鉴权、权限和账号状态

401 表示身份没有被认可。常见原因包括：请求头缺失或拼错，Key 有多余空格或已被轮换，把网页 Cookie 或临时 Token 当成 API Key，base URL 错误，或系统时间偏差导致签名失效。

403 表示身份被识别但无权访问。常见原因包括：Key 未开通对应模型，IP 不在白名单，地区受限，套餐过期，账号被风控，工作区权限不足。

处理顺序：

用最小请求复现，只保留鉴权头和必填参数。
对照文档确认请求头名称和前缀，注意 Bearer 后是否有空格。
在控制台确认 Key 状态、模型权限、余额和到期时间。
换一个新建的测试 Key；仍 403 就向服务商确认 IP、地区和账号池状态。

不要把 Key 写进前端代码或公开仓库。出现 401 时，先怀疑配置，不要连续重试，重试不会让错误的 Key 变正确。

三、429：限流、并发与额度

429 的含义比很多人想的宽。它可能表示每分钟请求数超限、并发任务数超限、当日额度用完、账号池暂时无可用账号，或者上游正在排队。不同原因的处理方式完全不同。

先看响应头和错误体：有 Retry-After 就按它等待；错误信息提到 quota 或 balance，通常是额度问题；提到 concurrency 或 queue，通常是并发问题；如果所有 Key 同时 429，可能是服务商账号池紧张。

应对方式：

客户端加队列，限制并发，不要瞬时打满。
使用指数退避加随机抖动，避免同一时刻集体重试。
区分“等一会儿能恢复”和“必须充值或提额”。
记录 429 的模型、时段和请求量，判断是自身流量还是上游容量。

429 不是多试几次就能解决；盲目重试会拉长排队，还可能延长封禁。

四、提示词被拒：审核与参数错误

“提示词被拒”有两类原因。一是内容审核：暴力、色情、未成年人、真实名人、受版权保护的角色、商标、政治人物等都可能触发。二是参数错误：画幅不支持、模型版本不存在、提示词过长、参考图 URL 无法访问或格式不支持。

这两类都不应该原样重试。内容审核拒绝要调整素材和表述，不要用同义词、拆字或隐晦描述反复绕过；参数错误要对照文档修正字段。记录被拒的提示词、模型版本和响应体，积累成团队的黑名单和检查规则。

还要区分“拒绝”和“失败”：前者通常发生在生成前，后者可能已经产生费用，具体以服务商规则为准。

五、任务失败、超时与结果过期

任务失败的原因包括上游内部错误、账号异常、参数不合法、参考图下载失败、审核中断和排队超时。先读错误字段，不要只看“failed”。

超时要分三种：客户端读超时，请求可能已到服务端；提交超时，任务可能已创建但响应没回来；轮询超时，任务仍在跑但等待窗口结束。

最危险的是提交超时后立刻重提，因为原任务可能已存在，结果就是重复扣费。正确做法：提交时带幂等键或业务请求号；超时后先按请求号查最近任务；确认不存在再重试。服务商不支持幂等键时，在任务表里做去重窗口。

结果过期是另一类问题。成功返回的往往是临时 URL，有效期从几分钟到几天不等，不能直接当作品地址存库。成功后应立即转存对象存储，数据库只保留自己的存储路径和任务 ID。

六、下载失败：403、404 与文件截断

下载失败不一定等于生成失败。常见情况有：签名 URL 过期返回 403；任务结果被清理返回 404；代理或网络中断导致连接重置；把 HTML 错误页当成图片保存；文件只下载了一半。

下载要单独设计：校验 Content-Type 和文件大小；先写临时文件，成功后再原子重命名；对 5xx 和网络错误重试；对 403、404 不要重试生成，而是查任务状态确认结果是否还在。服务商提供多个结果地址时，准备备用域名或转存通道。

七、重试与幂等：别让失败变成重复扣费

重试的原则是分类，而不是统一循环。401、403、400、422、内容审核拒绝，修配置或改提示词之前不要重试；429 按 Retry-After 等待；5xx、连接重置、读超时可以退避重试；提交超时先查任务再决定。

import random
import time
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def post_with_retry(url, headers, payload, request_id, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            resp = requests.post(
                url,
                headers={**headers, "Idempotency-Key": request_id},
                json=payload,
                timeout=(10, 60),
            )
        except (requests.Timeout, requests.ConnectionError):
            if attempt == max_attempts:
                raise
            time.sleep(min(2 ** attempt + random.random(), 30))
            continue

        if resp.status_code in RETRYABLE:
            retry_after = resp.headers.get("Retry-After", "")
            wait = int(retry_after) if retry_after.isdigit() else 2 ** attempt
            time.sleep(min(wait + random.random(), 60))
            continue

        if resp.status_code >= 400:
            raise RuntimeError(f"{resp.status_code}: {resp.text[:200]}")
        return resp.json()

    raise RuntimeError("retry budget exhausted")

示例里的 Idempotency-Key 只是常见写法，是否支持、字段名是什么，要以服务商文档为准。没有幂等键时，用业务请求号加任务表去重，同样能达到目的。

八、提交工单前的排查清单

记录发生时间、时区和持续时长。
附上请求 ID、任务 ID 和业务单号。
写明接口地址、模型名和接口版本。
附完整 HTTP 状态码和响应体，Key 与个人信息要脱敏。
说明请求参数、参考图数量和画幅，不要只写“生成失败”。
记录重试次数、间隔、网络环境和出口地区。
提供最小复现步骤，以及同参数换模型的结果。
说明影响范围：多少任务失败、是否影响线上交付。

工单里最有用的信息是具体模型、地区、时段、参数和三次请求 ID，而不是“接口不能用”。

九、监控与预防

把错误变成指标：按模型统计 401、403、429、5xx、任务失败、超时和下载失败比例；记录 P95 耗时；按天核对失败任务是否计费。给 429、任务失败率和下载失败率设阈值告警，而不是等投诉。

日常预防：按环境和项目拆分 Key，测试 Key 设额度上限，限制并发，给每类任务设最大重试次数和死信队列。使用第三方封装时，确认其状态页、响应时间和停运预案，别把全部流量压在没有 SLA 的通道上。

常见问题

401 换了 Key 还是报错怎么办？

先确认新 Key 已生效且有模型权限，再查请求头前缀、base URL 和系统时间。若其他模型正常，问题可能在上游账号池。

429 是不是余额不足？

不一定。429 可能是请求频率、并发数、额度或账号池容量。先看响应头和错误体，有 quota 或 balance 字样才更可能是额度问题。

任务超时后可以直接重提吗？

不建议。提交超时不代表任务没创建，直接重提可能重复扣费。应先用请求号或任务 ID 查询，确认不存在再重试；提交时尽量带幂等键。

结果链接过期了还能找回吗？

取决于服务商是否保留结果。先查任务状态，若已清理通常只能重新生成。生产环境应在成功后立即转存，避免依赖临时链接。

Midjourney 官方会处理第三方接口的报错吗？

不会。第三方封装与 Midjourney 官方无隶属关系，报错应由服务商排查；Midjourney 也没有公开 API 支持渠道。

下一步

先按“鉴权、限流、内容、任务、下载”五类归类错误，再决定哪些重试、哪些告警。需要统一入口，可以在中商起航 AI 网关创建 Key，并在模型价格页确认模型和计费。