Большинство ошибок Mistral API связаны не со способностями модели, а с учётными данными, путём, параметрами, лимитами или сетью. Порядок разбора должен быть таким: сначала HTTP-статус и тип ошибки, затем request ID в ответе и минимальное воспроизведение, и только потом правка промпта или смена модели. Обратный порядок легко превращает ошибку конфигурации в ложный вывод «модель плохая».

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

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

1. Сначала статус-код, потом промпт

Статус или симптом Обычный смысл Типичная причина Порядок действий
401 Аутентификация не пройдена Ключ отсутствует, повреждён или отозван Сначала исправить учётные данные
403 Нет прав Модель не подключена, роли workspace недостаточно, региональное ограничение Проверить аккаунт и права
404 Путь или модель не существует Неверный Base URL, дублирование пути, модель снята Проверить адрес и имя модели
422 Семантика запроса некорректна Нет поля, неверный тип, неподдерживаемый параметр Прочитать детали и исправить параметры
429 Сработал лимит или квота Резкий рост параллельности, общий ключ, шторм повторов Backoff, снижение параллельности
5xx Сбой вышестоящего сервиса Перегрузка, ошибка шлюза, временный сбой Ограниченные повторы, смена канала
Таймаут Таймаут соединения или чтения Сетевые колебания, длинный вывод, простой прокси Локализовать по слоям

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

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

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

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

403 — это «идентичность распознана, но прав нет». Частые причины: у аккаунта или workspace нет доступа к модели, роли недостаточно, модель не открыта для региона либо запрос идёт на неподключённый интерфейс. Сначала посмотрите список моделей и права участников в консоли, затем вызовите той же связкой ключей заведомо доступную модель для сравнения.

3. 404 и 422: адрес, имя модели и параметры

404 обычно означает не падение сервиса, а запрос к несуществующему пути или модели. Типичные причины: неверный Base URL, лишний или пропущенный /v1, SDK добавляет путь автоматически, а ручной код добавляет его ещё раз, используется снятая версия модели, а на шлюзе не настроен маршрут. Сначала отправьте минимальный запрос на полный адрес, изучите тело ошибки, затем сверьтесь со списком моделей в консоли.

422 говорит о том, что формат запроса корректен, но семантика недопустима. Частые случаи: отсутствует обязательное поле, неверный тип, пустой messages, max_tokens вне диапазона, параметр не поддерживается текущей моделью или повреждена структура JSON. В ответе обычно указаны поле и причина — прочитайте detail или error и исправьте, а не повторяйте запрос вслепую.

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

429 означает превышение лимита скорости, параллельности или квоты, а не нехватку баланса. Типичные сценарии:

  • Несколько сервисов используют один ключ и конкурируют за одну квоту.
  • Пакетные задания стартуют одновременно по расписанию и создают пик трафика.
  • Повторы выполняются без backoff: чем больше ошибок, тем больше запросов, и возникает шторм.
  • Длинные или потоковые ответы долго занимают соединения и сокращают запас для параллельных вызовов.
  • Тестовая, staging- и production-среды не разделены, и тестовый трафик выбирает производственную квоту.

Сначала проверьте, есть ли в ответе подсказка вроде Retry-After; если есть — ждите указанное время. Если нет — используйте экспоненциальный backoff со случайным джиттером. Одновременно снижайте параллельность, ставьте пакетные задания в очередь и применяйте token bucket, задавая лимиты по модели, ключу и среде. Повторы не заменяют масштабирование: они сглаживают краткие колебания, но не решают постоянную нехватку мощности.

5. 5xx и таймауты: вышестоящий сервис, сеть и стриминг

5xx включает 500, 502, 503 и 504: возможна перегрузка вышестоящего сервиса, сбой пересылки на шлюзе или временная неисправность. Сначала определите масштаб: падают все модели или конкретная модель, регион, маршрут. Кратковременные 5xx допускают ограниченные повторы; при постоянных 5xx снижайте параллельность, переключайтесь на резервный канал и сохраняйте request ID для обращения к платформе.

Таймауты делятся на соединение, чтение и простой потока. Таймаут соединения чаще связан с сетью, DNS или прокси; таймаут чтения — с длинным выводом, сложным рассуждением и очередью на стороне провайдера; в потоковом режиме соединение может разорвать прокси по простою. Клиент должен явно задавать таймауты соединения и чтения, а для стриминга — таймаут простоя и политику переподключения. Для запросов с побочными эффектами не отправляйте повтор сразу после таймаута: сначала выясните, не выполнил ли запрос вышестоящий сервис.

6. Request ID и логи: основа разбора

Request ID — якорь для разбора между командами. Он обычно присутствует в заголовках ответа или теле ошибки, часто в виде x-request-id. Независимо от того, идёт ли запрос напрямую или через шлюз, его нужно записывать и связывать в логах с номером бизнес-заказа.

Рекомендуемый минимум лога: время, request ID, статус, тип ошибки, имя модели, число входных и выходных токенов, длительность, число повторов, признак стриминга, вышестоящий канал. Пользовательский контент обезличивайте или храните в виде сводки, а от ключа оставляйте только префикс. По скриншоту ошибки без request ID команде поддержки трудно найти конкретный запрос.

7. Повторы и backoff: что можно повторять и как

Для повтора нужны три условия: ошибка восстановима, запрос можно безопасно повторить, число попыток ограничено. 401, 403, 404 и 422 не повторяйте — это проблемы конфигурации или параметров, повтор лишь тратит время. 429, 5xx и таймауты допускают ограниченные повторы с приоритетом Retry-After.

Пример ниже объединяет повторяемые статусы, экспоненциальный backoff, случайный джиттер и запись request ID. В production также нужны предохранитель (circuit breaker), отправка метрик и проверка идемпотентности бизнес-операции перед повторной отправкой.

import os
import random
import time

import requests

API_KEY = os.environ["MISTRAL_API_KEY"]
URL = "https://api.mistral.ai/v1/chat/completions"
RETRY_STATUS = {429, 500, 502, 503, 504}


def wait_seconds(resp, attempt):
    value = resp.headers.get("Retry-After") if resp is not None else None
    if value:
        try:
            return min(float(value), 60.0)
        except ValueError:
            pass
    return min(2 ** attempt + random.random(), 30.0)


def chat(payload, max_retries=4):
    last_error = None
    for attempt in range(max_retries + 1):
        try:
            resp = requests.post(
                URL,
                headers={
                    "Authorization": f"Bearer {API_KEY}",
                    "Content-Type": "application/json",
                },
                json=payload,
                timeout=(5, 60),  # соединение 5 с, чтение 60 с
            )
        except requests.Timeout as exc:
            last_error = exc
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(None, attempt))
            continue

        request_id = resp.headers.get("x-request-id", "unknown")
        if resp.status_code == 200:
            return resp.json()

        if resp.status_code in RETRY_STATUS:
            last_error = RuntimeError(
                f"HTTP {resp.status_code}, request_id={request_id}"
            )
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(resp, attempt))
            continue

        # 401/403/404/422 повторять бессмысленно: это конфигурация или параметры
        raise RuntimeError(
            f"HTTP {resp.status_code}, request_id={request_id}, "
            f"body={resp.text[:500]}"
        )

    raise RuntimeError(f"retry exhausted: {last_error}")

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

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

Перед обращением к поддержке платформы соберите информацию по списку — это заметно сокращает разбор:

  1. Время и интервал, с указанием часового пояса, а также характер сбоя: постоянный или эпизодический.
  2. Полный request ID, соответствующий статус и тело ошибки с обезличиванием.
  3. Адрес запроса, имя модели, признак стриминга, использование вызова инструментов или структурированного вывода.
  4. Один минимальный воспроизводимый запрос без лишних бизнес-полей, но с необходимыми параметрами.
  5. Масштаб: сколько пользователей, регионов и сетевых окружений затронуто, падают ли все модели.
  6. Недавние изменения: ротация ключей, обновление модели, правки прокси или шлюза.
  7. Уже выполненные проверки и результаты, включая сравнение с другим ключом, моделью, сетью и сниженной параллельностью.

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

Что делать, если 401 остаётся после замены ключа?

Сначала убедитесь, что новый ключ относится к платформе текущего Base URL, затем проверьте загрузку переменной окружения и передачу заголовка Authorization через прокси. Минимальные запросы напрямую к официальному входу и через шлюз быстро показывают, в чём проблема — в ключе или в маршруте.

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

Нет. 429 сообщает о превышении лимита скорости, параллельности или квоты; при нехватке баланса обычно возвращается другая ошибка или пояснение в теле ответа. Сначала проверьте параллельность, общие ключи и политику повторов, затем состояние аккаунта.

Чем 422 отличается от 400?

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

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

Зависит от побочных эффектов. Чистый запрос можно ограниченно повторить; для заказа, списания или отправки сообщения сначала выясните, не выполнил ли операцию вышестоящий сервис, либо используйте ключ идемпотентности. Таймаут означает лишь то, что клиент не дождался результата, а не то, что запрос не обработан.

Что подготовить перед созданием тикета?

Временной интервал, request ID, статус, тело ошибки, имя модели, минимальное воспроизведение и масштаб влияния. Дополнительно опишите недавние изменения и уже выполненные проверки — так поддержка быстрее найдёт конкретный маршрут.

10. Дальше

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

Полезное чтение: