Перед диагностикой ошибок Llama API нужно уточнить один факт: публичная предварительная версия Llama API от Meta была отключена 6 июля 2026 года. Если продолжать обращаться к старому адресу, чаще всего вы получите не 401 или 429, а уведомление об отключении либо перенаправление. Многие выводы «ключ не работает» и «модель не существует» на самом деле относятся к вызовам уже остановленного эндпоинта.

Сегодня Llama вызывают через сторонних хостинг-провайдеров, собственный инференс или единый шлюз. Аутентификация, Base URL, идентификаторы моделей, правила лимитирования и структура ошибок у платформ различаются, поэтому универсальной таблицы ошибок не существует. Ниже пять категорий — 401, 404, 429, тайм-ауты и ошибки 400 при вызове инструментов — с порядком диагностики и готовым кодом обработки. Модели и цены смотрите на странице цены на модели.

Примечание: Llama — товарный знак Meta Platforms, Inc. Интерфейсы, коды ошибок и правила лимитирования у хостинг-провайдеров могут меняться вместе с версиями. Примеры отражают типичную ситуацию на октябрь 2026 года; окончательно действует официальная документация соответствующей платформы.

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

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

Симптом Типичное значение Что проверить в первую очередь
Уведомление об отключении или перенаправление Запрос уходит на остановленный эндпоинт Домен и Base URL
401 Сбой аутентификации Ключ, заголовки, соответствие платформе
404 Путь или модель не найдены Base URL, путь, идентификатор модели
429 Лимит или квота Параллелизм, общий ключ, стратегия повторов
400 с упоминанием context length Переполнение контекста Длина входа, резерв под вывод
400 с упоминанием tool или JSON Неверный формат вызова инструментов Схема параметров, разбор, повторы
Тайм-аут Соединение, первый токен, чтение Сеть, длина входа, настройки тайм-аута
5xx Ошибка вышестоящего сервиса Повтор с задержкой, страница статуса платформы

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

2. 401: ключ и платформа должны соответствовать друг другу

401 означает, что личность не подтверждена; к возможностям модели и балансу это обычно отношения не имеет. У Llama нет универсального ключа: ключ старой платформы Meta не подойдёт стороннему хостинг-провайдеру, и наоборот. Другие частые причины:

  • В заголовке не используется Authorization: Bearer <key> либо есть ошибка в написании или регистре.
  • Вокруг ключа остались пробелы, переводы строки или кавычки — чаще всего при копировании из чата.
  • Переменная окружения фактически не загрузилась, и в среде развёртывания осталось старое значение.
  • Ключ удалён, ротирован или отключён, а планировщик по-прежнему использует старое значение.
  • Обратный прокси или шлюз перезаписал либо отбросил заголовок Authorization.
  • Проблема со статусом аккаунта или правами в регионе: ключ действителен, но доступа к модели нет.

Сначала отправьте минимальный запрос через curl и убедитесь, что ключ, Base URL и идентификатор модели проходят одновременно. Если 401 сохраняется, повторите проверку с новым ключом, чтобы отделить проблему ключа от прокси и шлюза. Не встраивайте ключ в клиент и не позволяйте фронтенду хранить его напрямую.

3. 404: Base URL, имя модели и отключённые эндпоинты

404 обычно означает не «модель сломалась», а то, что запрос ушёл на несуществующий адрес или модель. В 2026 году самый частый случай — старый адрес Meta из прежних инструкций уже отключён, и запрос возвращает 404 или уведомление об отключении. Другие причины:

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

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

4. 429: лимиты, квоты и шторм повторов

429 означает, что запрос превысил ограничение скорости, параллелизма или квоты. Правила у провайдеров разные: запросы в минуту, токены в минуту, суточная квота или уровень аккаунта — ориентируйтесь на документацию платформы. Типичные ситуации:

  • Несколько сервисов используют один ключ и отнимают квоту друг у друга.
  • Пакетные задачи стартуют одновременно по расписанию и создают пик трафика.
  • Повторы выполняются без задержки, и чем чаще ошибка, тем больше запросов — возникает шторм повторов.
  • Длинный контекст или длинный вывод занимает много токенов и сокращает пространство для параллельных запросов.
  • Бесплатная или пробная квота закончилась, а платформа продолжает отвечать 429 или похожей ошибкой.

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

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

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

  • Тайм-аут соединения: DNS, выходной маршрут или прокси недоступны, запрос ещё не дошёл до платформы.
  • Медленный первый токен: слишком длинный вход, очередь на платформе, высокая нагрузка на модель.
  • Тайм-аут чтения: слишком длинный вывод, долгое рассуждение, соединение разорвано промежуточным устройством.
  • Обрыв потока: нестабильная сеть или прокси, получена только часть ответа.
  • Тайм-ауты на всех запросах сразу: проблема локального выхода или вышестоящего сервиса, сначала проверьте страницу статуса платформы.

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

6. 400: переполнение контекста и формат вызова инструментов

Код 400 охватывает много ситуаций, поэтому сначала ищите ключевые слова в тексте ошибки. Упоминания context length, maximum tokens или input too long обычно означают переполнение контекста: вход плюс резерв под вывод превышают лимит модели. Действия: подсчитать токены, обрезать историю, сжать содержимое поиска или перейти на модель с более длинным контекстом. Не увеличивайте только max_tokens — это сокращает пространство для входа.

Упоминания tool, function, arguments или JSON обычно означают неверный формат вызова инструментов: неразбираемый JSON, отсутствующие обязательные поля, неверный тип параметра или несуществующее имя инструмента. Принципы обработки:

  1. Проверяйте параметры по JSON Schema, не собирайте строку вручную.
  2. При ошибке разбора верните модели сообщение об ошибке и ожидаемый формат, чтобы она исправилась один раз.
  3. Ограничьте число исправлений, чтобы не получить бесконечный цикл.
  4. Сохраняйте исходный ответ, чтобы отличить проблему модели от проблемы промпта.
  5. Для рискованных инструментов делайте повторную проверку и не доверяйте заявлению модели «выполнено».

7. Готовый код обработки ошибок

Пример использует OpenAI-совместимый интерфейс; Base URL и идентификатор модели читаются из переменных окружения, а автоматические повторы SDK отключены, чтобы не складывать их с собственной задержкой.

import os
import random
import time
import logging
from openai import (
    OpenAI, AuthenticationError, NotFoundError, RateLimitError,
    BadRequestError, APITimeoutError, APIStatusError,
)

logging.basicConfig(level=logging.INFO)
client = OpenAI(
    api_key=os.environ["LLAMA_HOST_API_KEY"],
    base_url=os.environ["LLAMA_HOST_BASE_URL"],  # совместимый адрес провайдера
    max_retries=0,
    timeout=90,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["LLAMA_MODEL_ID"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except AuthenticationError:
            raise  # ключ не соответствует платформе, повторять бессмысленно
        except NotFoundError as exc:
            logging.error("Проверьте Base URL и ID модели: %s", exc.request_id)
            raise
        except BadRequestError as exc:
            logging.error("Проблема в параметрах, контексте или формате инструмента: %s", exc.request_id)
            raise
        except (RateLimitError, APITimeoutError) as exc:
            wait = min(2 ** attempt, 20) + random.random()
            logging.warning("Попытка %s не удалась, повтор через %.1f с: %s",
                            attempt + 1, wait, exc.request_id)
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                logging.warning("Вышестоящий сервис вернул %s, повтор через %.1f с", exc.status_code, wait)
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Повторы исчерпаны, проверьте лимиты и настройки тайм-аута")

Повторы подходят только для кратковременных сбоев. 401, 404 и большинство ошибок 400 от повторов не исчезнут, а только раздуют журналы и счёт. В операциях с побочными эффектами сначала используйте идемпотентный ключ или проверку состояния, чтобы понять, выполнялся ли запрос.

8. Журналы, мониторинг и порядок диагностики

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

  1. Зафиксируйте код состояния, тип ошибки, request ID, платформу, Base URL, идентификатор модели и время.
  2. Если запрос идёт на старый адрес Llama API от Meta, сначала завершите миграцию.
  3. При 401 проверьте ключ, заголовки, переменные окружения и соответствие платформе.
  4. При 404 проверьте Base URL, путь /v1 и актуальный каталог моделей.
  5. При 429 проверьте параллелизм, общие ключи, стратегию повторов и часы пик.
  6. При тайм-ауте проверьте DNS, прокси, длину входа, время до первого токена и тайм-аут чтения.
  7. При 400 проверьте длину контекста, поддержку параметров и схему инструментов.
  8. При 5xx сначала повторите с задержкой, а если ошибка повторяется, обратитесь к платформе с request ID.

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

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

Llama API возвращает 401 — значит, ключ истёк?

Не обязательно. Чаще всего ключ не соответствует платформе: например, ключ старой платформы Meta используется у стороннего провайдера или наоборот. Проверьте заголовок, переменные окружения и платформу, которой принадлежит ключ, затем повторите минимальный запрос.

Почему после смены провайдера возвращается 404?

Изменился идентификатор модели. У платформ разные имена, префиксы, суффиксы версий и доступные регионы; старое имя на новой платформе обычно не существует. Заведите таблицу соответствия и ориентируйтесь на каталог моделей новой платформы.

При 429 нужно сразу повторять запрос?

Нет. Не начинайте с плотных повторов. Сначала снизьте параллелизм, затем добавьте экспоненциальную задержку со случайным разбросом и верхним пределом. Устойчивый 429 означает, что общего объёма или квоты не хватает: нужно разделить ключи, разнести нагрузку по времени или изменить квоту.

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

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

Что делать, если JSON параметров вызова инструмента не разбирается?

Сначала проверьте параметры по JSON Schema и сохраните исходный ответ; затем верните модели сообщение об ошибке и ожидаемый формат для одного исправления и ограничьте число попыток. Для рискованных инструментов нужна повторная проверка: заявлению модели об успехе доверять нельзя.

Дальше

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

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