Ошибки DeepSeek API: как найти причину и перейти на резервную модель

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

Руководство предназначено для разработчиков, использующих DeepSeek в приложении или при работе с кодом. Здесь есть диагностический запрос, таблица решений по ошибкам, конкретные кандидаты из каталога Ofox и скачиваемый пример резервного переключения на Python. Пример выполняет небольшую текстовую задачу без потоковой передачи. Он не переносит незаметно для приложения сессию агента и не выполняет инструменты.

Проверка от 19 октября 2026 года: мы сверили публичную документацию и каталог Ofox и выполнили 14 локальных синтетических тестов. Платных запросов к моделям мы не отправляли и сбой вышестоящего провайдера не воспроизводили. Наличие модели в каталоге не доказывает, что ваш аккаунт может её вызвать, что качество ответа подходит вашей задаче или что маршрут выдержит следующий инцидент. Статью публикует Ofox — один из рассматриваемых вариантов API-шлюза.

1. Определите, где возникла проблема: локально, в аккаунте или у провайдера

Начните со страницы состояния DeepSeek и сведений о состоянии шлюза, которым вы действительно пользуетесь. Зелёный статус полезен как ориентир, но не доказывает исправность вашего маршрута. Региональная проблема, только что начавшийся инцидент или ошибка отдельного аккаунта могут там ещё не отображаться.

До изменения настроек составьте краткую запись об инциденте:

Например, если один и тот же запрос не работает в приложении, но проходит в минимальном примере, проверяйте тело запроса, SDK, прокси и настройки тайм-аутов. Если одна модель не отвечает, а другая работает, область поиска сужается. Однако это не доказывает исправность всего шлюза: у моделей могут быть разные адаптеры и маршруты к провайдерам.

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

2. Выберите действие по типу ошибки

Скриншот официальной документации на английском языке сделан 19 октября 2026 года. Это справочная страница, а не результат неудачного вызова API.

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

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

DeepSeek описывает ограничения параллелизма на уровне аккаунта и отдельное поведение перегруженных запросов в руководстве по лимитам. Считайте активные запросы по всем обработчикам и API-ключам одного аккаунта. Замедление единственного обработчика может не устранить превышение общего лимита.

3. Выполните один небольшой диагностический запрос

Для прямого сервиса DeepSeek текущий документированный ID Flash — deepseek-flash. На шлюзе идентификатор может быть другим. Актуальное соответствие указано во введении в официальный API. Если подключаетесь впервые, воспользуйтесь нашим руководством по настройке DeepSeek API.

Используйте доверенную оболочку с отключённой трассировкой, уже настроенную переменную окружения из хранилища секретов и пустой рабочий каталог. Запрос ниже отправляет только синтетическую фразу. Он может тарифицироваться как обычный вызов модели. Не запускайте его многократно против перегруженного сервиса.

umask 077
curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 45 \
  --dump-header response-headers.txt \
  --output response-body.json \
  --write-out 'HTTP %{http_code}; total %{time_total}s\n' \
  https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model":"deepseek-flash","messages":[{"role":"user","content":"Reply with exactly: DIAGNOSTIC_OK"}],"stream":false,"max_tokens":128,"thinking":{"type":"disabled"}}'

Лимит соединения в 5 секунд и общий лимит в 45 секунд выбраны для диагностики; это не гарантии DeepSeek. Длительной задаче с рассуждениями может потребоваться другой срок ожидания. Опция --fail-with-body должна поддерживаться вашей версией curl; если она не распознаётся, проверьте curl --version. Не включайте подробную трассировку и не вставляйте команду с настоящим ключом в обращение в поддержку. Просмотр локальных процессов также может раскрыть подставленные аргументы команды; в общей среде используйте SDK с вашим менеджером секретов.

Полезный результат проверки — HTTP 200, полный непустой ответ с DIAGNOSTIC_OK и сведения о расходе, если они возвращены. Посмотрите choices[0].finish_reason: ответ, оборванный из-за лимита длины, не равноценен завершённому ответу. При ошибке сохраните её детали без конфиденциальных данных. Следующий запуск может перезаписать два указанных файла, поэтому для сравнения попыток используйте разные каталоги.

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

4. Выясните, какой резерв действительно поможет

Под резервным переключением, или fallback, часто понимают три разных изменения:

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

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

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

5. Подготовьте резервный маршрут Ofox с точным ID модели

19 октября публичный каталог моделей Ofox вернул следующие записи. Это проверка каталога, а не успешные вызовы моделей и не утверждение о превосходстве одной из них.

Для этих записей каталог указывает OpenAI Chat Completions. У двух записей DeepSeek встроенные возможности web_search и web_fetch отдельно отмечены как false. Не считайте, что возможности прямого DeepSeek Search/Fetch и правила их оплаты автоматически распространяются на ID модели Ofox. Резервное переключение в этой статье использует только текстовые Chat Completions, без встроенного поиска провайдера.

Порядок подготовки:

1. Проверьте текущую запись каталога, поддерживаемый протокол и цену, действующую для аккаунта. В статье не приводится цена Ofox и не обещается бесплатное использование.
2. Если маршрут соответствует требованиям, создайте аккаунт Ofox и ключ в разделе API Keys. Следуйте документации по авторизации. Ключ Ofox и прямой ключ DeepSeek относятся к разным аккаунтам.
3. Для OpenAI-совместимого маршрута укажите https://api.ofox.ai/v1 как базовый URL SDK. В прямом HTTP-запросе добавьте /chat/completions ровно один раз. Не допускайте /v1/v1 и не отправляйте на этот маршрут тело запроса в формате Anthropic Messages.
4. Скопируйте точный ID модели-кандидата, отправьте диагностическую задачу без конфиденциальных данных и проверьте ответ, расход и запись запроса. При необходимости отдельно пополните счёт после проверки условий аккаунта.
5. Добавляйте маршрут в рабочую схему переключения только после проверки типичных задач и расходов, описанной ниже.

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

6. Локально проверьте ограничения повторов и резервное переключение

Скачайте пример Python с тестами. Архив содержит failover.py, test_failover.py и README. Распакуйте его в новый каталог и выполните:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -m unittest -v

В нашем запуске 19 октября прошли 14 тестовых методов с подставными ответами и синтетическими учётными данными. Эти тесты не выполняют сетевых вызовов. Они проверяют успех основного маршрута, восстановление после 503, резерв после двух ошибок, HTTP-ошибки без продолжения, различие квоты и временного ограничения при 429, исчерпание попыток, транспортный сбой с неизвестным результатом, явное разрешение повторной отправки, сбой TLS, некорректный ответ со статусом успеха, а также Retry-After в виде числа и даты.

Контроллер разрешает максимум две попытки на основном маршруте и одну на резервном. Перед повтором или сменой маршрута он соблюдает Retry-After. Если задержка превышает его 30-секундный бюджет ожидания, пример останавливается, чтобы вызывающее приложение могло поставить задачу в очередь. Без пригодного заголовка используется ограниченная случайная задержка с увеличением интервала. Перенаправления отключены, чтобы адрес назначения не изменился неожиданно. Для каждого маршрута задаются собственные ключ и модель.

Для настоящих запросов установите переменные окружения через одобренный менеджер секретов:

DEEPSEEK_API_KEY = your direct DeepSeek key
BACKUP_BASE_URL  = https://api.ofox.ai/v1
BACKUP_MODEL     = deepseek/deepseek-v4.1-flash-1017
BACKUP_API_KEY   = your Ofox key
BACKUP_DISABLE_THINKING = 1

В примере your direct DeepSeek key означает ваш прямой ключ DeepSeek, а your Ofox key — ключ Ofox. Для показанного резервного DeepSeek параметр BACKUP_DISABLE_THINKING=1 явно отключает рассуждения ради короткого диагностического ответа. Если выбираете другое семейство моделей, удалите этот флаг и используйте документированные настройки с достаточным лимитом вывода. Не передавайте параметры DeepSeek автоматически другой модели. Эту конфигурацию ещё нужно проверить на реальном маршруте.

Затем запустите python failover.py. Команда отправляет фиксированный текстовый запрос и может повлечь расходы. Она выводит выбранный маршрут, запрошенную и возвращённую модель, текст, расход и ID запроса, если они доступны. Ожидаемый ответ — FALLBACK_TEST_OK; проверьте точное совпадение маркера самостоятельно. Успешная работа основного маршрута не проверяет реальный резерв. Для отдельной проверки резерва отправьте диагностический запрос напрямую на его документированный адрес; не перегружайте и не ломайте основной сервис намеренно.

При транспортных ошибках пример по умолчанию останавливается: сервер мог уже принять запрос. Команда python failover.py --allow-ambiguous-replay явно разрешает ещё одну попытку для этой фиксированной текстовой задачи без побочных действий. Она не разрешает повторять вызов инструмента, платёж, отправку письма или изменение файла. Даже чистая генерация может оплачиваться дважды.

Пример использует Requests напрямую, без скрытых повторов HTTP-ошибок внутри SDK. Если переносите политику в SDK, отключите его повторы либо учитывайте их в том же общем числе попыток. Тайм-аут соединения в 5 секунд и тайм-аут отсутствия данных при чтении в 30 секунд не задают общий предел длительности операции. Для рабочей системы также нужны общий срок выполнения, совместное управление параллелизмом, сохраняемое состояние автоматического отключения неисправного маршрута и проверка ответа по требованиям конкретной задачи.

7. Отдельно обрабатывайте потоковую передачу и выполнение инструментов

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

Для инструментов генерация и выполнение — разные этапы. Возвращённый моделью вызов инструмента ещё не доказывает, что действие выполнено. Обрыв сети после работы исполнителя также не доказывает неудачу действия. Ведите сохраняемый журнал действий с ID задачи, аргументами или безопасной ссылкой на них, состоянием выполнения и результатом. Перед продолжением выясняйте результат каждого действия с неизвестным исходом. Используйте поддержку идемпотентности конечного сервиса, если она есть; не придумывайте заголовок идемпотентности в расчёте на то, что провайдер его соблюдает.

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

8. Проверьте резерв, оцените расходы и верните основной маршрут

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

Записывайте маршрут, точную запрошенную модель, возвращённую модель при наличии, размер ввода, параметры, задержку, причину завершения, расход, запись списания и результат проверки. Отсутствующий расход неизвестен, а не равен нулю. Кэширование запроса на основном маршруте не доказывает попадание в кэш на резервном. При сверке счёта учитывайте неудачные и повторные попытки.

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

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

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

Критерий готовности конкретен: правильно установленная причина сбоя, проверенный предел повторов, одобренный резерв, который выполняет вашу реальную задачу, и восстановление без дублирования действий. Запись в каталоге и успешный HTTP-ответ — лишь промежуточные шаги к этому результату.