Ошибки Grok API делятся на четыре группы: учётные данные и права, путь и имя модели, ограничения частоты и квоты, сеть и тайм-ауты. Порядок разбора должен быть таким: сначала HTTP-код и тип ошибки, затем ID запроса, и только потом промпт или параметры модели. Если переставить порядок, конфигурационная проблема легко принимается за проблему модели.

Статья разбирает четыре класса — 401, 404, 429 и тайм-аут — и даёт причины, шаги диагностики и готовый код повторов с задержкой. Модели и цены смотрите на странице цены на модели.

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

1. Сначала смотрите код состояния, а не правьте промпт

Код Типичное значение Повторять
400 Проблема в параметрах, формате или длине контекста Исправить запрос и повторить
401 Ключ отсутствует, неверен, истёк или не соответствует адресу Не повторять, сначала исправить учётные данные
403 У аккаунта или ключа нет прав, либо ограничения региона и условий Не повторять, проверить права и состояние аккаунта
404 Неверный путь или несуществующее имя модели Не повторять, проверить адрес и имя модели
429 Превышены частота, параллелизм или токены Повторить с задержкой
500 Внутренняя ошибка вышестоящего сервиса Повторить с задержкой
502 или 503 Шлюз или вышестоящий сервис временно недоступен Повторить с задержкой
504 Шлюз превысил время ожидания вышестоящего сервиса Снизить нагрузку и повторить

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

2. 401: сначала заголовок, потом ключ

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

  1. Записан ли заголовок как Authorization: Bearer <Key>. Для OpenAI-совместимого входа Grok это не x-api-key.
  2. Нет ли перед ключом и после него пробелов, переводов строк или лишних кавычек. При копировании из чата это встречается чаще всего.
  3. Ключ и Base URL от одного поставщика? Официальный ключ с адресом шлюза или ключ шлюза с официальным адресом не сработают.
  4. Не отозван ли ключ, не истёк ли он, есть ли у его проекта право на вызов.
  5. Действительно ли загружены переменные окружения. Выведите только первые символы ключа, не пишите полное значение в лог.
  6. Указывает ли Base URL на нужное окружение и используется ли путь /v1/chat/completions.
export GROK_API_KEY="sk-ваш-ключ"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [{"role": "user", "content": "Ответь только OK"}],
    "max_tokens": 16
  }'

Ответ 200 означает, что ключ, адрес и имя модели в порядке. Если 401 сохраняется, проверьте тот же ключ через другой вход — так можно отделить проблему самого ключа от конфигурации шлюза или сети.

3. 404: проверьте путь и имя модели отдельно

404 обычно не связан с ключом: он означает, что запрошенного объекта не существует. Четыре частые причины:

  • Base URL уже содержит /v1, а код добавляет ещё один — получается /v1/v1/chat/completions.
  • Endpoint записан как /completions или /responses, хотя текущий вход предоставляет только Chat Completions.
  • Имя модели написано с ошибкой, либо модель не активирована для аккаунта или группы.
  • В конце Base URL лишний слэш, из-за чего после склейки появляется двойной слэш или неверный путь.

Порядок диагностики: сначала отправьте curl на стандартный путь из документации, затем скопируйте имя модели из консоли или со страницы цены на модели. Не пишите имя по памяти и не переносите имена моделей других платформ.

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

429 означает превышение скорости или квоты. Типичные сценарии:

  • Превышено число запросов или токенов в минуту.
  • Резко вырос параллелизм и на короткое время исчерпал квоту.
  • Несколько сервисов используют один ключ и вытесняют друг друга.
  • Повторы выполняются без задержки: чем больше ошибок, тем больше запросов — возникает «шторм повторов».
  • Длинный вывод занимает много выходных токенов и оставляет меньше места для параллельных запросов.
Симптом Возможная причина Что делать
429 сосредоточены в пиковые часы Импульс трафика Очередь и сглаживание отправки
429 при одном ключе на несколько сервисов Общая квота Разделить ключи по проектам
После повторов стало хуже Повторы без задержки Экспоненциальная задержка со случайным разбросом
Длинные запросы получают 429 первыми Высокий расход выходных токенов Снизить max_tokens или параллелизм

Сначала посмотрите на retry-after в ответе, если он есть, и только затем решайте, сколько ждать. Определяйте тип ошибки по классу исключения SDK, а не по строковому совпадению сообщения:

import random
import time
from openai import OpenAI, APIStatusError, RateLimitError

client = OpenAI(
    api_key="sk-ваш-ключ",
    base_url="https://ai.zhongshangqihang.com/v1",
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="grok-4",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, попытка {attempt + 1}, ожидание {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}, повтор через {wait:.1f}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Лимит повторов исчерпан")

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

5. Тайм-ауты и ошибки соединения

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

Порядок диагностики:

  1. Через curl запишите time_namelookup, time_connect, time_appconnect, time_starttransfer и посмотрите, на каком этапе уходит время.
  2. Проверьте, не задан ли в прокси слишком короткий тайм-аут соединения или простоя.
  3. Для длинного вывода включите потоковый режим: читайте по мере генерации, не ожидая полного ответа.
  4. Задайте отдельные тайм-ауты соединения и чтения; не полагайтесь на один большой общий тайм-аут.
  5. При повторе после тайм-аута проверьте, не выполнился ли запрос уже, чтобы не списать оплату и не записать данные дважды.
export GROK_API_KEY="sk-ваш-ключ"

curl -o /dev/null -s \
  -w "code=%{http_code} dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" \
  --max-time 120 \
  "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-4","messages":[{"role":"user","content":"Ответь только OK"}],"max_tokens":8}'

Если DNS и соединение быстрые, а первый байт приходит медленно, проблема скорее в генерации или вышестоящем сервисе. Если тайм-аут уже на этапе соединения, проверяйте выход и прокси, а не бизнес-код.

6. Таблица порядка диагностики

  1. Зафиксируйте код состояния, тип ошибки, ID запроса, имя модели и время.
  2. При 401 и 403 проверьте учётные данные, состояние аккаунта и права; при 404 — путь и имя модели.
  3. При 400 проверьте параметры, длину контекста, формат изображений и размер тела запроса.
  4. При 429 проверьте квоту, параллелизм, общий ключ и шторм повторов.
  5. При тайм-ауте разложите по этапам DNS, соединение, TLS, первый байт и общее время.
  6. При 5xx сначала повторите с задержкой; если ошибка держится, обратитесь к поставщику с ID запроса.
  7. После каждого инцидента добавляйте мониторинг и оповещения, не ждите, пока о проблеме сообщат пользователи.

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

Чем 429 отличается от нехватки баланса?

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

Почему после добавления повторов 429 стало больше?

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

Модель существует, но возвращается 404. Почему?

Проверьте, не дублируется ли /v1 в Base URL, и убедитесь, что endpoint — /chat/completions. Если путь верный, возможно, модель не активирована для аккаунта или группы, либо не совпадает регистр или суффикс версии в имени.

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

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

Как отличить ошибку шлюза от ошибки вышестоящего сервиса?

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

Что дальше

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

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