Ошибки CometAPI 401, 404, 429 и 5xx: повторить попытку или завершить с ошибкой?

Краткий ответ: не переключайтесь с Claude на GPT при каждом неудачном запросе. 401 означает, что нужно исправить аутентификацию, а связанный с путём 404 — что нужно корректировать URL или эндпоинт. 429 или временные 5xx можно повторить с бэкоффом; если ограниченные повторы всё же не помогают, может вступить совместимая запасная модель.

Эта статья была проверена 20 августа 2026 года по документации CometAPI по ошибкам, повторам, базовому URL, лимитам и фолбэку моделей. Здесь рассматривается только классификация ошибок. Для проектирования маршрутов, учётных данных провайдера и многоуровневого фейловера используйте полное руководство по фолбэку моделей и техническое руководство по фолбэку.

Начните с решения: повторять или завершить с ошибкой

Практический вопрос не «Сбой у Claude?», а «Может ли другая модель успешно обработать запрос без изменения некорректной его части?». Ошибки аутентификации и пути влияют на само соединение, поэтому смена модели их не решит. Временные проблемы мощности и сбои сервера могут быть маршрут‑специфичными, и здесь помогает фолбэк.

Прочитайте ошибку, прежде чем переключать модели

Используйте HTTP‑статус вместе с error.code и error.message. Многие ошибки CometAPI используют оболочку вида:

{
  "error": {
    "message": "human-readable detail and request id",
    "type": "comet_api_error",
    "param": "problematic_parameter_or_empty",
    "code": "error_code_or_empty"
  }
}

Не классифицируйте только по первой цифре кода статуса. 500 может нести invalid_request, а неверный путь CometAPI способен вернуть редирект или HTML вместо чистого JSON‑404.

401 Unauthorized: остановитесь и исправьте аутентификацию

401 обычно означает, что API‑ключ отсутствует, искажен, истёк или загружен из неверного окружения. Заголовок должен быть таким:

Authorization: Bearer $COMETAPI_KEY

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

404 Not Found: исправьте URL перед фолбэком

Для запросов, совместимых с OpenAI, используйте этот базовый URL в точности:

https://api.cometapi.com/v1

Отсутствующий /v1, дублированный сегмент пути или неверный эндпоинт могут привести к 404, редиректу, HTML‑ответу или ошибке парсинга в SDK. Отключите автоматическое следование редиректам при отладке и подтвердите конечный путь запроса по справочнику API.

Если в ответе явно указано, что модель недоступна или не найдена, проверьте ID модели в актуальном CometAPI Models API. Не рассматривайте каждый 404 как недоступность модели. Добавляйте фолбэк, специфичный для модели, только после фиксирования и проверки этого точного сигнала.

429 Too Many Requests: выполняйте бэкофф до фолбэка

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

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

Ошибки 5xx: проверьте код, затем повторите

500, 503, 504 и 524 часто указывают на сбои платформы, провайдера или таймаут‑класса. Сохраните идентификатор запроса, эндпоинт, модель и отметку времени, затем повторите с бэкоффом. Если тот же временный сбой переживает лимит повторов, переходите на следующий совместимый маршрут.

Но сначала проверьте тело ответа. Когда 500 содержит error.code: invalid_request или invalid_request_error, исправьте тело запроса и повторяйте только после его изменения. Частые причины: отсутствует поле messages или используется параметр, специфичный для провайдера, который выбранный эндпоинт не принимает.

Используйте одну маленькую политику в коде

Этот пример на Python держит повторы и фолбэк в приложении. Он использует один ключ CometAPI, совместимый с OpenAI базовый URL и переменные окружения для текущих ID моделей Claude и GPT. Он повторяет только временные сбои, затем меняет модели после исчерпания бюджета повторов.

import os, random, time
from openai import APIError, OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
    max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}

def complete(messages):
    for model in MODELS:
        for attempt in range(3):
            try:
                response = client.chat.completions.create(model=model, messages=messages)
                return response.choices[0].message.content
            except APIError as error:
                status = getattr(error, "status_code", None)
                code = getattr(error, "code", None)
                if status in {401, 404} or code in {
                    "invalid_request", "invalid_request_error"
                }:
                    raise
                if status not in RETRYABLE:
                    raise
                if attempt < 2:
                    time.sleep(2**attempt + random.random())
                    continue
                break
    raise RuntimeError("No configured route completed.")

print(complete([{"role": "user", "content": "Summarize this ticket."}]))

Автоповторы SDK отключены, чтобы приложение контролировало общий бюджет повторов и фолбэка. Без этого контроля повторы SDK плюс повторы приложения могут умножить вызовы и задержать финальный ответ.

Тестируйте политику без догадок

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

Когда фолбэк с Claude на GPT действительно безопасен

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

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

Производственные проверки, удерживающие повторы в границах

• Установите единый бюджет общей задержки. Считайте каждый повтор и фолбэк в один и тот же дедлайн.
• Ограничьте повторы. Используйте бэкофф с джиттером и останавливайтесь после небольшого лимита.
• Контролируйте конкуррентность. Снижайте всплески до того, как запросы покидают приложение.
• Добавьте автомат «предохранитель» (circuit breaker). Временно прекращайте вызовы постоянно падающего маршрута.
• Логируйте решения. Фиксируйте статус, код ошибки, ID запроса, модель, попытку, задержку и причину фолбэка без сохранения секретов.
• Отслеживайте долю фолбэков. Устойчивый рост — это операционный сигнал, а не нормальная метрика успеха.

Часто задаваемые вопросы

Должен ли 401 когда‑либо запускать фолбэк модели?

Нет. Исправьте или перезагрузите API‑ключ. Другая модель, вызываемая с теми же неверными учётными данными, упадёт по той же причине.

Должен ли 404 запускать фолбэк?

Не по умолчанию. Сначала исправьте базовый URL или эндпоинт. Только отдельно проверенный сигнал «модель недоступна» должен попадать в классификатор фолбэка.

Сколько раз повторять 429?

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

Все ли ошибки 5xx подлежат повтору?

Нет. Временные 500, 503, 504 и 524 — кандидаты для повтора, но 500 с invalid_request должен приводить к немедленному фейлу до исправления тела запроса.

Могут ли Claude и GPT использовать один и тот же неизменённый запрос?

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

Где находится полная реализация фолбэка?

См. How to Build Robust LLM Model Fallback Strategies для общей архитектуры и CometAPI model fallback guide для деталей реализации.

Сделайте классификатор ошибок привратником

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

Источники

• CometAPI error codes and handling
• CometAPI error and retry strategy
• CometAPI rate limits and concurrency
• CometAPI base URL guide
• CometAPI model and provider fallback guide
• CometAPI complete model fallback tutorial