Ошибки MiniMax API делятся примерно на четыре слоя: HTTP-статус, бизнес-код в теле ответа, таймаут на транспортном уровне и сбой вышестоящего сервиса. При разборе сначала определите слой, потом ищите причину — не начинайте с правки промпта или смены модели. Многие жалобы «модель плохая» в итоге оказываются неверным Key, смешением адресов или слишком коротким таймаутом.

Ниже разобраны 401, 403, 404, 429, 5xx и таймауты: причины, порядок проверки и переиспользуемый код обработки ошибок. Названия моделей, цены и квоты уточняйте в официальной документации и на странице тарифов.

Примечание: MiniMax — товарный знак своего правообладателя. Коды ошибок, уровни лимитов и поведение интерфейсов могут меняться; статья описывает типичную ситуацию на октябрь 2026 года, окончательно ориентируйтесь на официальную документацию MiniMax.

1. Сначала слои: статус, бизнес-код, таймаут

Официальная документация MiniMax выносит бизнес-коды отдельно и просит при обращении в поддержку указывать trace_id из заголовков ответа. Документация по лимитам ограничивает запросы по трём измерениям: RPM, TPM и число параллельных задач. Смотреть нужно и HTTP-уровень, и бизнес-уровень: часть нативных интерфейсов может вернуть HTTP 200, а ошибку положить в base_resp тела ответа; OpenAI-совместимый вход обычно выражает ошибку HTTP-статусом. Записывайте оба уровня, иначе часть проблем останется незамеченной.

Симптом Частое значение Что проверить сначала Действие
401, 1004, 2049 Ошибка аутентификации или недействительный Key Key, заголовок Bearer, соответствие адреса Выпустить новый Key и сделать минимальный запрос
403 Права, состояние аккаунта или ограничение входа Права на модель, статус верификации, квота на шлюзе Сверить с консолью и телом ответа
404 Путь или модель не существует Base URL, /v1, не выведена ли модель Открыть официальный список моделей
400, 2013, 1039 Ошибка параметров или превышение токенов thinking, temperature, max_tokens Ужать параметры по документации
429, 1002, 2045, 1041, 2056 Лимит частоты, параллельности или окна тарифа RPM, TPM, общий Key, всплеск трафика Задержка, очередь, разделение ключей
1008 Недостаточно средств Баланс, квота подписки Пополнить или сменить способ оплаты
Таймаут, 1001 Таймаут соединения или чтения Сеть, прокси, длинный вывод, настройки стриминга Настроить таймауты по слоям
5xx, 1024, 1033 Сбой вышестоящего сервиса Статус сервиса, можно ли повторить запрос Повтор с ограничением и задержкой

В логах фиксируйте как минимум время, статус, бизнес-код, имя модели, длительность и trace_id. Не записывайте полный Key и не печатайте пользовательский текст целиком.

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

401 означает, что подлинность запроса не подтверждена, и обычно не связана со способностями модели. Проверяйте по порядку:

  • Заголовок должен быть Authorization: Bearer <key>, а не самодельная схема аутентификации.
  • Нет ли в Key пробелов, переводов строк или кавычек — при копировании из чата это самая частая проблема.
  • Действительно ли загружена переменная окружения; можно вывести только первые символы.
  • Не удалён ли Key, не ротирован ли он и не отключён ли.
  • Относятся ли Base URL и Key к одной платформе: официальный Key с адресом шлюза даст 401.
  • Не перезаписывает ли обратный прокси заголовок Authorization.
  • Не смешаны ли Key подписки M Plan и Key оплаты по факту. Официальная документация указывает, что это независимые системы, их квоты не взаимозаменяемы.

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

3. 404: чаще всего ошибаются в Base URL и имени модели

404 обычно означает не «интерфейс упал», а запрос к несуществующему пути или модели. Частые причины:

  • Base URL записан как адрес другого поставщика либо содержит лишний или пропущенный /v1.
  • SDK сам добавляет /chat/completions, а при ручном пути его добавляют ещё раз.
  • Имя модели относится к снятой версии или отличается регистром либо суффиксом.
  • Официальный адрес и адрес шлюза смешаны, а правила путей у них разные.
  • Правило перезаписи в обратном прокси испортило путь.

Официальный список моделей MiniMax показывает, что исторические текстовые модели M2.5 и M2.7 находятся в процессе вывода: для новых пользователей обслуживание прекращается с 19 октября 2026 года, полное отключение планируется 18 ноября 2026 года. В текущей документации указаны текстовые модели MiniMax-M3 и MiniMax-M3.1-Flash. Если продолжать использовать старое имя, можно получить 404 или бизнес-ошибку. Перед миграцией сверьте имя в официальном списке моделей и на странице тарифов.

4. 429: лимит частоты — это не нехватка баланса

429 означает, что запрос превысил ограничение скорости, параллельности или квоты. Официальная документация MiniMax ограничивает RPM (запросы в минуту), TPM (входные и выходные токены в минуту) и число параллельных задач; основной и дочерние аккаунты используют общую квоту. Для текущих моделей M3 и M3.1-Flash документация указывает базовые уровни: 20 RPM для бесплатных пользователей и 200 RPM для пополненных, TPM — 1 млн и 10 млн соответственно; точные значения смотрите в консоли.

Типичные причины срабатывания:

  • Несколько сервисов используют один Key и вытесняют друг друга.
  • Пакетные задачи стартуют одновременно в начале часа, создавая всплеск.
  • Повторы идут без задержки, и каждая неудача порождает новые запросы.
  • Длинный вывод или рассуждение занимает ресурсы и сокращает доступную параллельность.
  • Окно тарифа закончилось и сработало ограничение M Plan.

Что делать: разделить ключи по проектам; пропускать пакетные задачи через очередь; ограничить число повторов, добавить экспоненциальную задержку и случайный разброс; отдельно ограничить длинные задачи; если в ответе есть Retry-After, соблюдать его. Получив 429, не наращивайте параллельность — сначала выровняйте поток запросов.

5. Таймауты и 5xx: различайте соединение, первый токен и чтение

Таймаут не равен недоступности сервиса. Сначала определите, на каком участке он возник:

  • Таймаут соединения: DNS, выход в сеть или прокси недоступны; проверьте сеть и прокси.
  • Медленный первый токен: очередь на стороне сервиса или слишком длинный промпт; сократите вход, сместите нагрузку или возьмите более лёгкую модель.
  • Таймаут чтения: слишком длинный вывод или долгие рассуждения; увеличьте таймаут чтения и ограничьте вывод.
  • Обрыв стрима: сетевая нестабильность или обрыв на прокси; клиент должен уметь переподключаться и отбрасывать дубли.
  • Таймаут асинхронной задачи: для видео и речи различайте «задача в очереди» и «истёк таймаут запроса»; опрашивайте по task_id и не отправляйте задачу повторно.

5xx и бизнес-коды 1000, 1024, 1033 обычно указывают на сбой или перегрузку вышестоящего сервиса. Такие ошибки подходят для повторов с задержкой, но с ограничением. Для операций с побочными эффектами сначала проверьте идемпотентным ключом или запросом статуса, выполнялись ли они. Ссылка на скачивание асинхронного аудио имеет срок действия (по текущей документации — 9 часов), после истечения её нужно получать заново.

6. Код обработки ошибок: задержка, trace_id и логи

import logging
import os
import random
import time

import httpx
from openai import (
    APITimeoutError,
    APIStatusError,
    AuthenticationError,
    OpenAI,
    RateLimitError,
)

log = logging.getLogger("minimax")
client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # отключаем автоповторы SDK, логика ниже управляет ими сама
)

def trace_id(exc: Exception) -> str:
    response = getattr(exc, "response", None)
    headers = getattr(response, "headers", {}) or {}
    return headers.get("trace_id") or headers.get("x-request-id") or "-"

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["MINIMAX_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content or ""
        except AuthenticationError as exc:
            log.error("Ошибка аутентификации status=%s trace_id=%s", exc.status_code, trace_id(exc))
            raise
        except RateLimitError as exc:
            wait = min(2 ** attempt, 30) + random.uniform(0, 1)
            log.warning("Сработал лимит attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APITimeoutError as exc:
            wait = min(2 ** attempt, 15) + random.uniform(0, 1)
            log.warning("Таймаут запроса attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 30) + random.uniform(0, 1)
                log.warning("Ошибка вышестоящего сервиса status=%s attempt=%s wait=%.1fs trace_id=%s",
                            exc.status_code, attempt + 1, wait, trace_id(exc))
                time.sleep(wait)
                continue
            log.error("Клиентская ошибка status=%s detail=%s trace_id=%s",
                      exc.status_code, exc, trace_id(exc))
            raise
    raise RuntimeError("Повторы исчерпаны; обратитесь к поставщику с trace_id")

print(ask("Объясни одним предложением, что такое лимит API"))

Этот код делает четыре вещи: различает повторяемые и неповторяемые ошибки, добавляет экспоненциальную задержку с разбросом, пишет trace_id в лог и отдельно обрабатывает 5xx. Он не заменяет идемпотентность: для запросов с побочными эффектами сначала проверяйте статус.

7. Логи и мониторинг: минимум полей

  • Время и проект: помогают найти пик и оценить зону влияния.
  • HTTP-статус и бизнес-код: различают аутентификацию, лимиты, параметры и сбои вышестоящего сервиса.
  • trace_id или x-request-id: ключевое доказательство для разбора с поставщиком.
  • Адрес интерфейса и имя модели: показывают, не появилась ли ошибка после смены модели или входа.
  • Входные и выходные токены: нужны для анализа стоимости и длинных запросов.
  • Длительность, число повторов и параллельность: выявляют хвостовые задержки и шторм повторов.
  • Псевдоним Key: статистика по проектам без записи самого ключа.

Мониторинг должен как минимум почасово считать 401, 403, 404, 429, таймауты и 5xx. При резком росте ошибок сначала проверьте, не сосредоточены ли они в одном проекте, на одном Key или одной модели, и только потом решайте, снижать параллельность, переключать канал или откатывать версию.

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

  1. Время, часовой пояс, длительность и затронутые интерфейсы.
  2. HTTP-статус, бизнес-код и полное сообщение об ошибке; чувствительные данные обезличить.
  3. trace_id из заголовков ответа и возможный x-request-id, добавленный шлюзом.
  4. Адрес интерфейса, имя модели, версия SDK и параметры запроса.
  5. Минимальный воспроизводимый curl без бизнес-данных и персональной информации.
  6. Прямое подключение или шлюз; используется Key оплаты по факту или Key M Plan.
  7. Параллельность, RPM/TPM, число повторов и наличие всплеска трафика в это время.
  8. Меняли ли недавно модель, версию SDK, настройки прокси или шлюза.
  9. Если код 1008 — приложите скриншот баланса или статуса тарифа, также обезличенный.

Одно сообщение с этими данными помогает гораздо быстрее, чем «выдаёт ошибку». Поставщик обычно первым делом спрашивает trace_id и временное окно.

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

429 — это нехватка баланса?

Нет. 429 означает превышение скорости, параллельности или квоты; нехватке баланса обычно соответствует бизнес-код 1008. Сначала проверьте параллельность, общий Key и всплески трафика.

Почему HTTP 200 тоже может быть ошибкой?

Часть нативных интерфейсов MiniMax выражает бизнес-ошибку через base_resp.status_code в теле ответа, а HTTP-уровень остаётся 200. Для таких интерфейсов код должен разбирать тело, а не только статус; OpenAI-совместимый вход обычно возвращает HTTP-код ошибки напрямую.

Где взять trace_id?

Официальная документация по ошибкам указывает читать trace_id из заголовков ответа. При работе через шлюз может дополнительно возвращаться x-request-id — записывайте оба.

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

Нет. Повторы должны иметь предел, задержку и оповещение; таймаут может означать, что запрос уже выполняется на стороне сервиса. Для операций с побочными эффектами сначала проверьте статус, потом решайте, отправлять ли снова.

Что делать с 404 после смены модели?

Сначала проверьте, не снята ли модель, затем — нет ли лишнего или пропущенного /v1 в Base URL. Исторические текстовые модели MiniMax выводятся партиями, и старое имя нельзя считать доступным; ориентируйтесь на официальный список моделей и страницу тарифов.

Что дальше

Создайте тестовый Key в ZSQH AI Gateway, отработайте по одному разу 401, 404, 429 и таймаут, затем подключайте производственный мониторинг. Доступность моделей и цены — на странице тарифов.

Похожие материалы: