Обрабатывать ошибки CometAPI проще всего, если разделять проблемы со структурой запроса, проблемы с аутентификацией, ошибки пути, и сбои платформы, допускающие повтор. Используйте сочетание HTTP-статуса, error.code и error.message, чтобы решить, нужно ли исправить запрос или повторить его.
Быстрая диагностика
Контейнер ошибки
Во многих сбоях CometAPI используется тело ошибки такого вида:
В некоторых ответах code остаётся пустым. Если статус — 500, рассматривайте error.code и error.message как решающий сигнал.
400 Bad Request
400 обычно означает, что тело запроса не прошло валидацию до того, как запрос мог быть нормально обработан.
Распространённые причины:
- Отсутствуют обязательные поля, такие как
model
- Неверная структура JSON
- Поле передаётся с неправильным типом
- Повторное использование специфичных для провайдера параметров, которые выбранный endpoint не принимает
Начните с минимального заведомо корректного запроса, затем добавляйте необязательные поля обратно по одному. Сравните payload со схемой endpoint в справочнике API.
Используйте минимальный запрос, например такой:
Замените your-model-id на любой актуальный model ID со страницы CometAPI Models page.
Не предполагайте, что каждый некорректный chat-запрос возвращает 400. Отсутствие обязательных chat-полей, таких как messages, также может проявляться как 500 с error.code: invalid_request.
500 Internal Server Error
Большинство ответов 500 указывают на сбой платформы или провайдера. Для Chat Completions некоторые некорректные запросы также могут проявляться как 500, при этом всё равно содержать error.code: invalid_request.
Один из примеров — запрос, в котором отсутствует messages:
Если ответ 500 содержит error.code: invalid_request, считайте это проблемой запроса:
- Исправьте тело запроса.
- Сравните payload со схемой endpoint.
- Повторяйте только после исправления payload.
Если ответ 500 не указывает на недопустимый запрос, сохраните request id и используйте backoff.
401 Invalid Token
Сбой token обычно выглядит так:
Что проверить:
- Заголовок должен быть строго
Authorization: Bearer $COMETAPI_KEY.
- Убедитесь, что ваше приложение не загружает старый ключ из
.env, истории shell или хранилища секретов в развернутом окружении.
- Если один ключ не работает, а другой работает с тем же запросом, считайте это проблемой token, а не проблемой endpoint.
403 Forbidden
403 чаще всего означает одну из следующих ситуаций:
- Запрос блокируется правилом на стороне платформы, например фильтрацией WAF
- Token или route не разрешено использовать запрошенную model или форму запроса
- Выбранная model отклоняет один из переданных вами расширенных параметров
Что сделать в первую очередь:
- Повторите запрос с очень простым текстовым запросом к заведомо рабочей model.
- Удалите расширенные поля и provider-specific параметры, затем постепенно добавляйте их обратно.
- Если ответ содержит request id, сохраните его перед обращением в поддержку.
Если в сообщении упоминаются внутренние термины, такие как group или channel, считайте их деталями маршрутизации, а не первым, что нужно диагностировать со стороны клиента. Практическое решение по-прежнему состоит в том, чтобы сначала проверить token, model и форму запроса.
Неверный base URL или неверный path
В Comet ошибка в path может проявляться как:
- Перенаправление
- Не-JSON HTML-ответ, если ваш клиент следует перенаправлениям
- Ошибка парсинга внутри вашего SDK
- Запрос, который так и не доходит до API-уровня корректным образом
Используйте этот base URL без изменений:
Рекомендуемые проверки:
- Убедитесь, что base URL включает
/v1.
- Убедитесь, что path endpoint в точности соответствует документации.
- Отключите автоматическое следование перенаправлениям при отладке проблем с path.
413 Request Entity Too Large
Если вы видите 413, в первую очередь считайте это проблемой размера запроса. Частые причины:
- Большие payload в base64
- Слишком большие изображения или аудио, встроенные inline
- Очень большие multipart- или JSON-body
Что делать:
- Уменьшите или сожмите прикрепленный контент.
- Разделите большие задачи на несколько меньших запросов.
- Не предполагайте, что причина только в длине обычного текста.
429 Too Many Requests
Считайте 429 ошибкой, которую можно повторить:
- Используйте exponential backoff с jitter.
- Снизьте burst concurrency.
- Оставьте логирование запросов включенным, чтобы видеть, какой route и какая model первыми упираются в насыщение.
Готовый шаблон повторных попыток см. в примере backoff на странице Chat Completions.
503, 504, и 524
Эти статусы означают сбои на стороне сервера или ошибки класса timeout.
Практические рекомендации:
503: route или provider service временно недоступен504 и 524: ошибки класса timeout между платформой, edge или provider service
Что делать:
- Повторите запрос с backoff.
- Сохраните
request id, endpoint, model и временную метку.
- Если один и тот же сбой повторяется в нескольких попытках, обратитесь в поддержку, приложив этот контекст.
Перед обращением в поддержку
Сначала соберите эти данные:
- HTTP-метод
- Путь endpoint
- Model ID
- Очищенный JSON тела запроса (это самый полезный пункт для большинства API-вызовов)
- Параметры запроса, если в неудачном запросе они использовались
- Точное тело ответа, если ваш клиент его сохранил
- Полный HTTP-статус
- Точный
error.message
- Любой
request id
- Примерная временная метка
- Работает ли тот же запрос с другой моделью или другим token
Если проблемный маршрут принимает загрузку файлов (редактирование изображений, загрузка аудио, генерация видео и т. д.) вместо обычного JSON-тела, отправьте эквивалентный переданный payload:
- Имена полей и текстовые значения, которые вы отправляли вместе с файлом
- Имя файла, тип файла и примерный размер файла
- Был ли файл загружен напрямую, указан по URL или встроен как base64
Самый эффективный способ воспроизвести баг — это точный очищенный payload запроса. Для большинства API-вызовов это означает сырой JSON тела запроса. Для маршрутов с загрузкой файлов — список полей плюс метаданные файла.
