Коды ошибок и их обработка

Устраняйте сбои запросов CometAPI с помощью проверенных рекомендаций для ошибок 400, 401 и ошибок пути, а также практических советов по обработке 403, 429 и сбоев класса timeout.

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

Это руководство основано на проверках в реальном времени текущего API CometAPI. Мы напрямую подтвердили ошибки 400, 401 и сбои пути/base URL. Мы не воспроизводили 413, 429, 500, 503, 504 или 524 в ограниченных тестах, поэтому рекомендации для этих статусов намеренно даны с осторожностью.

​

Быстрая диагностика

Status	Что это обычно означает	Повторять запрос?	Первое действие
400	Валидация запроса не прошла до того, как запрос был успешно маршрутизирован.	Нет	Проверьте model, messages, структуру JSON и типы полей.
401	API key отсутствует, имеет неверный формат или недействителен.	Нет	Проверьте Authorization: Bearer <COMETAPI_KEY>.
403	Доступ был заблокирован или текущий запрос не разрешён.	Обычно нет	Повторите запрос с заведомо рабочим запросом и сначала уберите поля, специфичные для модели.
Ошибка пути	Неверный base URL или неверный путь endpoint. В Comet это может проявляться как редирект 301 или HTML, а не как корректный JSON 404.	Нет	Используйте строго https://api.cometapi.com/v1 и отключите автоматический переход по редиректам во время отладки.
429	Ограничение скорости запросов или временная перегрузка.	Да	Используйте exponential backoff с jitter.
500, 503, 504, 524	Сбой платформы или сбой класса timeout.	Да	Повторите запрос с backoff и сохраните request id.

​

Структура ошибки

Текущая JSON-структура ошибки, возвращаемая CometAPI, выглядит так:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Во многих сообщениях об ошибках из реального API также присутствует request id внутри error.message. Сохраняйте это значение, если вам потребуется обратиться в поддержку.

​

400 Bad Request

Вот что мы наблюдали в реальном API, когда model был пропущен:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

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

Типичные причины:

• Отсутствуют обязательные поля, такие как model или messages
• Неверная структура JSON
• Поле отправлено с неправильным типом
• Используются параметры, специфичные для провайдера, которые выбранный endpoint не принимает

Что делать:

1. Начните с минимального заведомо рабочего запроса.
2. Возвращайте необязательные поля по одному.
3. Сравните тело запроса со схемой endpoint в API reference.

Минимальный заведомо рабочий пример:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Замените your-model-id на любой актуальный идентификатор модели со страницы CometAPI Models page.

​

401 Invalid Token

Вот что мы наблюдали в реальном API при использовании недействительного ключа:

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

Что проверить:

1. Заголовок должен быть строго Authorization: Bearer <COMETAPI_KEY>.
2. Убедитесь, что ваше приложение не загружает старый ключ из .env, истории shell или хранилища секретов в развернутом окружении.
3. Если один ключ не работает, а другой работает с тем же запросом, считайте это проблемой токена, а не проблемой endpoint.

​

403 Forbidden

Мы не воспроизвели стабильный 403 в ограниченных тестах, поэтому не стоит считать один старый шаблон сообщения исчерпывающим объяснением.

В текущей документации Comet 403 чаще всего рассматривается как одна из следующих ситуаций:

• Запрос блокируется правилом на стороне платформы, например фильтрацией WAF
• token или route не имеют права использовать запрошенную model или форму запроса
• Выбранная model отклоняет один из переданных вами расширенных параметров

Что сделать в первую очередь:

1. Повторите запрос с очень простым текстовым запросом к заведомо рабочей model.
2. Удалите расширенные поля и provider-specific параметры, затем постепенно добавляйте их обратно.
3. Если ответ включает request id, сохраните его перед обращением в поддержку.

Если в сообщении упоминаются внутренние термины, такие как group или channel, воспринимайте их как детали маршрутизации, а не как первое, что нужно диагностировать со стороны клиента. На практике сначала всё равно нужно проверить token, model и форму запроса.

​

Неверный Base URL или неверный путь

Это та область, где старая страница была наименее точной.

При проверках текущих endpoint’ов Comet:

• Отправка запроса на https://api.cometapi.com/chat/completions возвращала редирект 301 на https://www.cometapi.com/chat/completions
• Отправка запроса на несуществующий API route, такой как https://api.cometapi.com/v1/not-a-real-endpoint, тоже возвращала редирект 301 на https://www.cometapi.com/v1/not-a-real-endpoint

Это означает, что ошибка в пути может проявляться как:

• Редирект
• Не-JSON HTML-ответ, если ваш клиент следует редиректам
• Ошибка парсинга внутри вашего SDK
• Запрос, который вообще не доходит до API-слоя корректным образом

Используйте этот base URL в точности:

https://api.cometapi.com/v1

Рекомендуемые проверки:

1. Убедитесь, что base URL включает /v1.
2. Убедитесь, что путь endpoint’а в точности соответствует документации.
3. На время отладки проблем с путями отключите автоматическое следование редиректам.

​

413 Request Entity Too Large

Мы не воспроизвели 413 в ограниченном тесте даже с чрезмерно большим JSON request body размером 8 MiB, поэтому старое объяснение, что prompt был слишком длинным, было слишком узким.

Если вы всё же видите 413, сначала рассматривайте это как проблему размера запроса. Обычные причины:

• Большие payload’ы в base64
• Слишком большие изображения или аудио, встроенные inline
• Очень большие multipart или JSON body

Что делать:

1. Уменьшите или сожмите прикреплённый контент.
2. Разделите большие задачи на более мелкие запросы.
3. Не предполагайте, что единственная причина — это длина обычного текста.

​

429 Too Many Requests

Мы не воспроизвели 429 во время ограниченной проверки параллелизма с 24 параллельными запросами GET /v1/models, поэтому точный порог явно зависит от route, model и текущего состояния платформы.

Считайте 429 ошибкой, которую можно повторно запрашивать:

1. Используйте exponential backoff с jitter.
2. Уменьшите burst-параллелизм.
3. Не отключайте логирование запросов, чтобы видеть, какой route и какая model начинают насыщаться первыми.

Готовый шаблон повторных попыток см. в примере backoff на странице Chat Completions.

​

500, 503, 504 и 524

Мы не воспроизвели эти статусы в ограниченных тестах. Их следует документировать как ошибки на стороне сервера или сбои класса timeout, а не как ошибки пользователя.

Практические пояснения:

• 500: внутренний сбой платформы или ошибка на стороне provider
• 503: route или сервис provider временно недоступен
• 504 и 524: сбои класса timeout между платформой, edge или сервисом provider

Что делать:

1. Повторите запрос с backoff.
2. Сохраните request id, endpoint, model и timestamp.
3. Если одна и та же ошибка повторяется после нескольких попыток, обратитесь в поддержку, передав этот контекст.

​

Перед тем как обращаться в поддержку

Сначала соберите следующие данные:

• HTTP-метод
• Путь endpoint
• Название модели
• Очищенный JSON тела запроса (это самый полезный пункт для большинства API-вызовов)
• Параметры запроса, если проблемный запрос их использовал
• Точное тело ответа, если ваш клиент его сохранил
• Полный HTTP-статус
• Точное значение error.message
• Любой request id
• Примерная временная метка
• Работает ли тот же запрос с другой моделью или другим токеном

Если проблемный route принимает загрузку файлов (редактирование изображений, загрузка audio, генерация video и т. д.) вместо обычного JSON body, отправьте эквивалентный переданный payload:

• Имена полей и текстовые значения, которые вы отправляли вместе с файлом
• Имя файла, тип файла и примерный размер файла
• Был ли файл загружен напрямую, указан по URL или встроен как base64

Самый быстрый способ воспроизвести баг — это точный очищенный payload запроса. Для большинства API-вызовов это означает raw JSON тела запроса. Для route с загрузкой файлов это означает список полей плюс метаданные файла.

Это значительно сокращает время обработки обращения в поддержке.