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

Ниже четыре класса разобраны по отдельности: причины, шаги диагностики и готовый код задержек. Модели и цены — на странице цены на модели.

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

1. Сначала различите четыре класса ошибок

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

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

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

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

  1. Используется ли в заголовке Authorization: Bearer <key>, а не другой способ аутентификации.
  2. Нет ли вокруг ключа пробелов, переводов строки или лишних кавычек. При копировании из чата они появляются чаще всего.
  3. Действительно ли загружена переменная окружения — можно вывести только префикс.
  4. Не удалён ли ключ, не выполнен ли его ротацию или отключение.
  5. Относятся ли Base URL и ключ к одной платформе: официальный ключ с адресом шлюза даёт 401.
  6. Не перезаписал ли или не отбросил ли заголовок Authorization обратный прокси.
export DEEPSEEK_API_KEY="sk-ваш-ключ"

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

Если команда возвращает 200, значит ключ, Base URL и имя модели верны. Если по-прежнему 401, создайте новый ключ и повторите минимальный запрос — так вы отделите проблему ключа от настройки прокси или шлюза.

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

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

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

Начните с curl по полному адресу и посмотрите текст ошибки в ответе, затем сверьте Base URL и имя модели со страницей цен. Не прописывайте несколько адресов жёстко в коде — настраивайте по среде, чтобы адрес тестовой среды не ушёл в продакшен.

4. 429: это не всегда нехватка средств

429 означает превышение скорости, параллелизма или квоты. В часы пик DeepSeek может ограничивать или ставить запросы в очередь; точные правила — в официальной документации. Типичные ситуации:

  • Несколько сервисов используют один ключ и конкурируют за квоту.
  • Пакетные задачи стартуют одновременно в начале часа и создают всплеск.
  • Повторы идут без задержки: чем больше сбоев, тем больше запросов — шторм повторов.
  • Длинный вывод или задачи рассуждения занимают больше ресурсов, оставляя меньше места параллелизму.
Симптом Возможная причина Действие
429 сосредоточены в часы пик Нагрузка провайдера или всплеск трафика Очередь, равномерная отправка, смещение по времени
429 при одном ключе на несколько сервисов Общая квота Разделить ключи по проектам
После повторов стало хуже Повторы без задержки Экспоненциальная задержка со случайным разбросом
Длинные запросы получают 429 первыми Высокий расход выходных токенов Снизить max_tokens или параллелизм 
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError

client = OpenAI(
    api_key="sk-ваш-ключ",
    base_url="https://api.deepseek.com",
    max_retries=0,  # отключаем автоповторы SDK, чтобы не дублировать свою логику
)

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

print(ask("Объясни одной фразой, что такое ограничение скорости"))

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

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

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

Симптом Возможная причина Действие
Тайм-аут соединения DNS, выход в сеть, недоступный прокси Проверить сеть и прокси, сменить маршрут
Медленный первый токен Очередь у провайдера, слишком длинный промпт Сократить вход, сместить нагрузку, взять лёгкую модель
Тайм-аут чтения Слишком длинный вывод, долгие рассуждения Увеличить тайм-аут чтения, ограничить вывод
Обрыв потока Сетевая нестабильность, обрыв на прокси Поддержать переподключение, сохранять принятое
Тайм-ауты во всех сервисах сразу Локальный выход или сбой провайдера Переключиться на резервный канал, проверить статус 
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-ваш-ключ",
    base_url="https://api.deepseek.com",
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)

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

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

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

7. Мониторинг и журналы

Поле Назначение
Время и проект Определить пик и зону влияния
Код состояния и тип ошибки Отличить аутентификацию, лимиты и сбой провайдера
Request ID Ключевое доказательство для обращения к провайдеру
Имя и версия модели Понять, не появилась ли ошибка после смены модели
Входные и выходные токены Проанализировать стоимость и длинные запросы
Длительность и число повторов Выявить хвостовую задержку и шторм повторов

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

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

429 — это нехватка средств?

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

Какая самая частая причина 404?

Неверный Base URL, двойная склейка пути и устаревшее имя модели. Отправьте curl по полному адресу и сверьте имя модели со страницей цен — обычно это занимает несколько минут.

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

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

Что делать при обрыве потокового вывода?

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

Как отличить ошибку шлюза от ошибки официального входа?

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

Что дальше

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

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