Перейти до основного вмісту

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 status, error.code і error.message, щоб визначити, чи потрібно виправити запит, чи повторити його.

​
Швидка діагностика

StatusЩо це зазвичай означаєПовторювати?Перша дія
400Валідація запиту не пройшла до того, як запит було оброблено у звичайному режимі.НіПеревірте model, messages, структуру JSON і типи полів.
401Ключ API відсутній, має неправильний формат або є недійсним.НіПеревірте Authorization: Bearer <COMETAPI_KEY>.
403Доступ було заблоковано або поточний запит не був дозволений.Зазвичай ніПовторіть запит із відомо коректним запитом і спочатку приберіть поля, специфічні для моделі.
Path mistakeНеправильний base URL або неправильний шлях endpoint. У Comet це може проявлятися як перенаправлення 301 або HTML, а не як чистий JSON 404.НіВикористовуйте рівно https://api.cometapi.com/v1 і вимкніть автоматичне слідування перенаправленням під час налагодження.
429Обмеження частоти запитів або тимчасове перевантаження.ТакВикористовуйте exponential backoff з jitter.
500 with error.code: invalid_requestНекоректний запит проявився через відповідь зі статусом сервера.НіВиправте тіло запиту перед повторною спробою.
500, 503, 504, 524Збій платформи, провайдера або тайм-ауту.ТакПовторіть із backoff і збережіть request id.

​
Контейнер помилки

Багато збоїв CometAPI використовують таке тіло помилки: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
У деяких відповідях code залишається порожнім. Якщо status дорівнює 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. Не припускайте, що кожен некоректний 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 filtering
  • token або route не має дозволу використовувати запитану model або форму запиту
  • Обрана model відхиляє один із переданих вами розширених параметрів
Що зробити спочатку:
  1. Повторіть запит із дуже простим текстовим запитом до відомої справної model.
  2. Приберіть розширені поля та provider-specific параметри, а потім поступово додавайте їх назад.
  3. Якщо відповідь містить request id, збережіть його перед зверненням до підтримки.
Якщо повідомлення згадує внутрішні терміни, такі як group або channel, сприймайте їх як деталі маршрутизації, а не як перше, що потрібно діагностувати на стороні клієнта. Практичне рішення все одно полягає в тому, щоб спочатку перевірити token, model і форму запиту.

​
Неправильний base URL або неправильний path

У Comet помилка в path може проявлятися як:
  • Перенаправлення
  • Відповідь HTML не у форматі JSON, якщо ваш клієнт виконує перенаправлення
  • Помилка парсингу всередині вашого 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 body
Що робити:
  1. Зменште розмір або стисніть вкладений content.
  2. Розбийте великі завдання на менші запити.
  3. Не припускайте, що єдиною причиною є лише довжина звичайного тексту.

​
429 Too Many Requests

Сприймайте 429 як помилку, яку можна повторити:
  1. Використовуйте exponential backoff з jitter.
  2. Зменште burst concurrency.
  3. Залишайте логування запитів увімкненим, щоб бачити, які route і model першими досягають насичення.
Для повторно використовуваного шаблону retry дивіться приклад backoff на сторінці Chat Completions.

​
503, 504, and 524

Ці статуси є збоями на стороні сервера або збоями класу timeout. Практичні вказівки:
  • 503: route або сервіс provider тимчасово недоступний
  • 504 і 524: збої класу timeout між платформою, edge або сервісом provider
Що робити:
  1. Повторіть запит із backoff.
  2. Збережіть request id, endpoint, model і часову мітку.
  3. Якщо той самий збій повторюється в кількох повторних спробах, зверніться до підтримки з цим контекстом.

​
Перш ніж звертатися до служби підтримки

Спочатку зафіксуйте такі деталі:
  • HTTP-метод
  • Шлях endpoint
  • Model ID
  • Очищений request body JSON (це найкорисніший елемент для більшості API-викликів)
  • Параметри запиту, якщо проблемний запит їх використовував
  • Точне response body, якщо ваш клієнт його зафіксував
  • Повний HTTP-статус
  • Точне error.message
  • Будь-який request id
  • Приблизна позначка часу
  • Чи працює той самий запит з іншою model або іншим token
Якщо проблемний маршрут приймає завантаження файлів (редагування зображень, завантаження аудіо, генерація відео тощо) замість звичайного JSON body, надішліть еквівалентний відправлений payload:
  • Назви полів і текстові значення, які ви надіслали разом із файлом
  • Ім’я файлу, тип файлу та приблизний розмір файлу
  • Чи було файл завантажено безпосередньо, вказано через URL або вбудовано як base64
Найефективніший спосіб відтворити баг — це точний очищений request payload. Для більшості API-викликів це означає сирий request body JSON. Для маршрутів із завантаженням файлів це означає список полів плюс метадані файлу.
Це суттєво скорочує час відповіді служби підтримки.