Перейти к основному содержанию

Documentation Index

Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

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

Во многих ошибках CometAPI используется тело ответа такого вида: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
В некоторых ответах поле code остаётся пустым. Если статус — 500, рассматривайте error.code и error.message как основной сигнал для принятия решения.

​
400 Bad Request

400 обычно означает, что тело запроса не прошло валидацию до того, как запрос мог быть обработан обычным образом. Частые причины:
  • Отсутствуют обязательные поля, например model
  • Некорректная структура JSON
  • Поле передано с неверным типом
  • Повторное использование параметров, специфичных для провайдера, которые выбранный endpoint не принимает
Начните с минимального заведомо корректного запроса, затем добавляйте необязательные поля обратно по одному. Сравните payload со схемой endpoint в справочнике API. Используйте минимальный запрос такого вида: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Замените 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: 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Если ответ 500 содержит error.code: invalid_request, воспринимайте это как проблему запроса:
  1. Исправьте тело запроса.
  2. Сравните payload со схемой endpoint.
  3. Повторяйте только после исправления payload.
Если ответ 500 не указывает на некорректный запрос, сохраните request id и используйте backoff.

​
401 Invalid Token

Сбой token обычно выглядит так: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
Что проверить:
  1. Заголовок должен быть строго Authorization: Bearer <COMETAPI_KEY>.
  2. Убедитесь, что ваше приложение не загружает старый ключ из .env, истории shell или хранилища секретов в развернутой среде.
  3. Если один ключ не работает, а другой ключ работает с тем же запросом, рассматривайте это как проблему token, а не endpoint.

​
403 Forbidden

403 чаще всего означает одну из следующих ситуаций:
  • Запрос блокируется правилом на стороне платформы, например фильтрацией WAF
  • token или route не имеет права использовать запрошенную модель или форму запроса
  • Выбранная модель отклоняет один из переданных вами расширенных параметров
Что сделать в первую очередь:
  1. Повторите запрос с очень простым текстовым запросом к заведомо рабочей модели.
  2. Удалите расширенные поля и provider-specific параметры, затем постепенно добавляйте их обратно.
  3. Если ответ содержит request id, сохраните его перед обращением в поддержку.
Если в сообщении упоминаются внутренние термины, такие как group или channel, воспринимайте их как детали маршрутизации, а не как первое, что нужно диагностировать на стороне клиента. Практическое решение по-прежнему состоит в том, чтобы сначала проверить token, модель и форму запроса.

​
Неверный base URL или неверный path

В Comet ошибка в path может проявляться так:
  • Редирект
  • Не-JSON HTML-ответ, если ваш клиент следует редиректам
  • Ошибка парсинга внутри вашего SDK
  • Запрос, который так и не доходит до API-слоя корректным образом
Используйте этот base URL без изменений: 
https://api.cometapi.com/v1
Рекомендуемые проверки:
  1. Убедитесь, что base URL включает /v1.
  2. Убедитесь, что path endpoint в точности соответствует документации.
  3. Отключите автоматическое следование редиректам при отладке проблем с path.

​
413 Request Entity Too Large

Если вы видите 413, в первую очередь рассматривайте это как проблему размера запроса. Частые причины:
  • Большие payload в base64
  • Слишком большие изображения или аудио, встроенные inline
  • Очень большие multipart- или JSON-тела
Что делать:
  1. Уменьшите размер или сожмите прикрепленный контент.
  2. Разбивайте большие задачи на более мелкие запросы.
  3. Не предполагайте, что причина только в длине обычного текста.

​
429 Too Many Requests

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

​
503, 504, и 524

Эти статусы означают ошибки на стороне сервера или сбои класса timeout. Практические ориентиры:
  • 503: route или сервис provider временно недоступен
  • 504 и 524: сбои класса timeout между платформой, edge или сервисом provider
Что делать:
  1. Повторяйте запрос с backoff.
  2. Сохраняйте request id, endpoint, model и timestamp.
  3. Если одна и та же ошибка повторяется в нескольких попытках, обратитесь в поддержку с этим контекстом.

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

Сначала соберите следующие данные:
  • HTTP-метод
  • Путь endpoint
  • Model ID
  • Санитизированный JSON тела запроса (это самый полезный элемент для большинства API-вызовов)
  • Параметры запроса, если в проблемном запросе они использовались
  • Точное тело ответа, если ваш клиент его сохранил
  • Полный HTTP-статус
  • Точное значение error.message
  • Любой request id
  • Примерная временная метка
  • Работает ли тот же запрос с другой моделью или другим токеном
Если проблемный маршрут принимает загрузку файлов (редактирование изображений, загрузка аудио, генерация видео и т. д.) вместо обычного JSON body, отправьте эквивалентный переданный payload:
  • Имена полей и текстовые значения, которые вы отправляли вместе с файлом
  • Имя файла, тип файла и примерный размер файла
  • Был ли файл загружен напрямую, указан по URL или встроен как base64
Самый эффективный способ воспроизвести баг — это точный санитизированный payload запроса. Для большинства API-вызовов это означает raw request body JSON. Для маршрутов с загрузкой файлов это означает список полей плюс метаданные файла.
Это значительно сокращает время обработки обращения в поддержке.