Разработчики, которые ищут «ошибки Midjourney API», обычно не находят официальной таблицы кодов. У Midjourney нет универсального публичного API, и вы чаще всего вызываете стороннюю обёртку или шлюз-посредник, а коды состояния, поля ошибок и правила повторов определяет провайдер. Один и тот же 401 на двух платформах может означать разные причины.

Статья классифицирует типовые сбои по семантике HTTP и жизненному циклу задачи, даёт порядок диагностики, примеры повторов и идемпотентности, а также чек-лист для обращения в поддержку. Интерфейсы, коды ошибок и биллинг определяются документацией провайдера.

Примечание: Midjourney — товарный знак Midjourney, Inc.; Discord — товарный знак Discord Inc. Рассматриваемые сторонние обёртки и посредники не связаны с этими компаниями; интерфейсы, коды ошибок и биллинг определяются документацией провайдера.

1. Сначала определите уровень ошибки

Один вызов проходит пять уровней: клиент и сеть, аутентификация на шлюзе, пул аккаунтов upstream, задача генерации, хранение результатов и CDN. Сбои на разных уровнях выглядят по-разному:

Симптом Вероятный уровень Первый шаг
Все интерфейсы падают Клиент, сеть, DNS, прокси Сменить сеть или воспроизвести минимальным запросом
Падает только Midjourney Канал или пул аккаунтов upstream Проверить статус провайдера и другие модели
На этапе отправки возвращается 4xx Аутентификация, параметры, лимиты Сверить запрос с кодами ошибок
Отправка успешна, задача failed Генерация, модерация, аккаунт upstream Прочитать поле ошибки задачи
Задача успешна, изображение не открывается Ссылка результата, CDN, скачивание Проверить срок ссылки и повторить скачивание

При диагностике сначала ответьте на три вопроса: падает всё или отдельные вызовы? Ошибка при отправке или при выполнении задачи? Воспроизводится стабильно или только в часы пик? Эти ответы вдвое сужают область поиска.

2. 401 и 403: аутентификация, права и состояние аккаунта

401 означает, что идентичность не подтверждена. Частые причины: заголовок отсутствует или набран с ошибкой, в ключе лишние пробелы или он уже ротирован, вместо API Key передан веб-Cookie или временный токен, неверен base URL, системное время сильно расходится и подпись недействительна.

403 означает, что идентичность распознана, но доступа нет. Частые причины: ключу не открыта модель, IP отсутствует в белом списке, регион ограничен, подписка истекла, аккаунт попал под риск-контроль, не хватает прав рабочего пространства.

Порядок действий:

  1. Воспроизведите минимальным запросом, оставив только заголовок аутентификации и обязательные параметры.
  2. Сверьте с документацией имя и префикс заголовка, обратите внимание на пробел после Bearer.
  3. В консоли проверьте состояние ключа, права на модель, баланс и срок действия.
  4. Попробуйте новый тестовый ключ; если 403 остаётся, уточните у провайдера IP, регион и состояние пула аккаунтов.

Не записывайте ключ во фронтенд-код или публичный репозиторий. При 401 сначала подозревайте конфигурацию и не повторяйте подряд: повтор не сделает неверный ключ правильным.

3. 429: лимиты, параллельность и квота

Значение 429 шире, чем кажется. Это может быть превышение запросов в минуту, лимита одновременных задач, дневной квоты, отсутствие свободных аккаунтов в пуле или очередь upstream. Способы реагирования совершенно разные.

Сначала смотрите заголовки и тело ошибки: при наличии Retry-After ждите указанное время; упоминание quota или balance обычно означает квоту; concurrency или queue — параллельность; если все ключи одновременно получают 429, вероятно, у провайдера напряжён пул аккаунтов.

Что делать:

  • Добавьте очередь на клиенте и ограничьте параллельность, не отправляйте всё мгновенно.
  • Используйте экспоненциальную задержку со случайным разбросом, чтобы не повторять синхронно всей системой.
  • Различайте «подождать и восстановится» и «нужно пополнить баланс или поднять лимит».
  • Записывайте модель, время и объём запросов при 429, чтобы понять, ваш это трафик или ёмкость upstream.

429 не решается несколькими дополнительными попытками: слепые повторы удлиняют очередь и могут продлить блокировку.

4. Отказ промпта: модерация и ошибки параметров

«Промпт отклонён» имеет две группы причин. Первая — модерация контента: насилие, сексуальный контент, несовершеннолетние, реальные знаменитости, защищённые авторским правом персонажи, товарные знаки, политические фигуры. Вторая — ошибки параметров: неподдерживаемый формат кадра, несуществующая версия модели, слишком длинный промпт, недоступный URL референса или неподдерживаемый формат.

Обе группы не стоит повторять как есть. При отказе модерации меняйте материалы и формулировки, а не пытайтесь обходить проверку синонимами, разбиением символов или намёками. Ошибки параметров исправляйте по документации. Сохраняйте отклонённые промпты, версию модели и тело ответа, формируя командный чёрный список и правила проверки.

Различайте «отказ» и «сбой»: первый обычно происходит до генерации, второй может уже стоить денег; конкретика — в правилах провайдера.

5. Сбой задачи, тайм-аут и истечение результата

Причины сбоя задачи: внутренняя ошибка upstream, проблема аккаунта, недопустимые параметры, неудачное скачивание референса, прерывание модерации и тайм-аут в очереди. Сначала читайте поле ошибки, а не только слово «failed».

Тайм-ауты бывают трёх видов: тайм-аут чтения на клиенте — запрос мог дойти до сервера; тайм-аут отправки — задача могла создаться, но ответ не вернулся; тайм-аут опроса — задача ещё выполняется, но окно ожидания закончилось.

Самое опасное — сразу повторно отправить задачу после тайм-аута отправки: исходная задача могла уже существовать, и получится двойное списание. Правильно: передавать ключ идемпотентности или номер бизнес-запроса; после тайм-аута сначала искать последнюю задачу по номеру; повторять только после подтверждения, что её нет. Если провайдер не поддерживает ключ идемпотентности, сделайте окно дедупликации в таблице задач.

Истечение результата — отдельная проблема. Успешный ответ часто содержит временный URL со сроком от минут до дней, и его нельзя сохранять в базу как адрес работы. После успеха сразу переносите файл в объектное хранилище, а в базе храните собственный путь и ID задачи.

6. Сбой скачивания: 403, 404 и обрезанный файл

Ошибка скачивания не равна ошибке генерации. Частые случаи: подписанный URL истёк и вернул 403; результат задачи очищен и вернул 404; прокси или сеть разорвали соединение; HTML-страница ошибки сохранена как изображение; файл скачан только наполовину.

Скачивание проектируйте отдельно: проверяйте Content-Type и размер файла; сначала пишите во временный файл и только после успеха атомарно переименовывайте; повторяйте при 5xx и сетевых ошибках; при 403 и 404 не повторяйте генерацию, а проверяйте статус задачи и наличие результата. Если провайдер даёт несколько адресов результата, подготовьте резервный домен или канал сохранения.

7. Повторы и идемпотентность: не превращайте сбой в двойное списание

Принцип повторов — классификация, а не единый цикл. 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 в примере — распространённый вариант; поддержку и точное имя поля уточняйте в документации. Без ключа идемпотентности тот же эффект даёт номер бизнес-запроса плюс дедупликация в таблице задач.

8. Чек-лист перед обращением в поддержку

  1. Зафиксируйте время, часовой пояс и длительность.
  2. Приложите ID запроса, ID задачи и номер бизнес-заказа.
  3. Укажите адрес интерфейса, название модели и версию API.
  4. Приложите полный HTTP-статус и тело ответа, замаскировав ключ и персональные данные.
  5. Опишите параметры запроса, число референсов и формат кадра, а не просто «генерация не удалась».
  6. Запишите число повторов, интервалы, сетевую среду и регион выхода.
  7. Дайте минимальные шаги воспроизведения и результат смены модели при тех же параметрах.
  8. Укажите масштаб: сколько задач упало и затронута ли продакшн-доставка.

Самое полезное в обращении — конкретная модель, регион, время, параметры и три ID запросов, а не фраза «интерфейс не работает».

9. Мониторинг и профилактика

Превратите ошибки в метрики: считайте по моделям долю 401, 403, 429, 5xx, сбоев задач, тайм-аутов и неудачных скачиваний; фиксируйте задержку P95; ежедневно проверяйте, оплачиваются ли неудачные задачи. Настройте пороги оповещения для 429, доли сбоев и неудачных скачиваний, не дожидаясь жалоб.

Ежедневная профилактика: разделяйте ключи по средам и проектам, ставьте лимиты тестовым ключам, ограничивайте параллельность, задавайте максимальное число повторов и очередь недоставленных задач для каждого типа. При использовании сторонней обёртки проверьте её страницу статуса, время реакции и план остановки; не направляйте весь трафик в канал без SLA.

Частые вопросы

401 остаётся после смены ключа — что делать?

Убедитесь, что новый ключ активен и имеет права на модель, затем проверьте префикс заголовка, base URL и системное время. Если другие модели работают, проблема может быть в пуле аккаунтов upstream.

429 означает нехватку баланса?

Не обязательно. 429 может означать частоту запросов, параллельность, квоту или ёмкость пула аккаунтов. Смотрите заголовки и тело: слова quota или balance повышают вероятность проблемы с квотой.

Можно ли сразу повторно отправить задачу после тайм-аута?

Не рекомендуется. Тайм-аут отправки не означает, что задача не создана; повтор может привести к двойному списанию. Сначала проверьте по номеру запроса или ID задачи и повторяйте только при отсутствии записи; по возможности передавайте ключ идемпотентности.

Можно ли восстановить истёкшую ссылку на результат?

Зависит от того, хранит ли провайдер результаты. Сначала проверьте статус задачи; если результат очищен, обычно остаётся только повторная генерация. В production сохраняйте файл сразу после успеха, не полагаясь на временную ссылку.

Обрабатывает ли Midjourney ошибки сторонних интерфейсов?

Нет. Сторонние обёртки не связаны с Midjourney, и ошибки должен разбирать провайдер; у Midjourney также нет публичного канала поддержки API.

Что дальше

Сначала классифицируйте ошибки по пяти группам — «аутентификация, лимиты, контент, задача, скачивание» — и решите, что повторять, а что отправлять в оповещения. Для единой точки входа создайте ключ в ZSQH AI Gateway и проверьте модели и биллинг на странице тарифов.

Читайте также: