Перейти до основного вмісту
Обробка помилок у CometAPI найпростіша, коли ви розділяєте проблеми запиту, проблеми автентифікації та платформені проблеми, які можна повторити. Ця сторінка є канонічним довідником з помилок CometAPI і зосереджується на тому, що ви можете спочатку перевірити з боку клієнта.
Цей посібник ґрунтується на перевірках у реальному часі поточного API CometAPI. Ми безпосередньо перевірили збої 400, 401 і помилки шляху/base URL. Ми не відтворювали 413, 429, 500, 503, 504 або 524 у контрольованих тестах, тому рекомендації для цих статусів навмисно є консервативними.

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

StatusЩо це зазвичай означаєПовторити?Перша дія
400Валідація запиту не пройшла до того, як запит був успішно маршрутизований.НіПеревірте model, messages, JSON-структуру та типи полів.
401API key відсутній, некоректно сформований або недійсний.НіПеревірте Authorization: Bearer <COMETAPI_KEY>.
403Доступ було заблоковано або поточний запит не дозволено.Зазвичай ніПовторіть із гарантовано коректним запитом і спочатку приберіть поля, специфічні для model.
Path mistakeНеправильний 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"
	}
}
Багато реальних повідомлень про помилки також містять request id всередині error.message. Зберігайте це значення, коли вам потрібна підтримка.

​
400 Bad Request

Ось що ми спостерігали в live API, коли було пропущено model: 
{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}
На практиці 400 зазвичай означає, що тіло запиту не пройшло валідацію до того, як платформа змогла маршрутизувати його до провайдера model. Поширені причини:
  • Відсутні обов’язкові поля, такі як model або messages
  • Невалідна JSON-структура
  • Надсилання поля з неправильним типом
  • Повторне використання параметрів, специфічних для провайдера, які вибраний endpoint не приймає
Що робити:
  1. Почніть із мінімального гарантовано коректного запиту.
  2. Додавайте необов’язкові поля назад по одному.
  3. Порівняйте тіло запиту зі схемою endpoint у довіднику API.
Мінімальний гарантовано коректний приклад: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Замініть your-model-id на будь-який актуальний ID model зі сторінки CometAPI Models page.

​
401 Invalid Token

Ось що ми спостерігали в live 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
  • Токену або маршруту не дозволено використовувати запитувану модель або форму запиту
  • Вибрана модель відхиляє один із переданих вами розширених параметрів
Що робити насамперед:
  1. Повторіть запит із дуже простим текстовим запитом до завідомо справної моделі.
  2. Приберіть розширені поля та специфічні для провайдера параметри, а потім поступово додавайте їх назад.
  3. Якщо у відповіді є request id, збережіть його перед зверненням до служби підтримки.
Якщо в повідомленні згадуються внутрішні терміни, такі як group або channel, сприймайте їх як деталі маршрутизації, а не як перше, що потрібно діагностувати з боку клієнта. Практичне рішення все одно полягає в тому, щоб спочатку перевірити токен, модель і форму запиту.

​
Неправильний Base URL або неправильний шлях

Це розділ, у якому стара сторінка була найменш точною. Під час перевірок поточних endpoint-ів Comet:
  • Надсилання запиту до https://api.cometapi.com/chat/completions повертало редирект 301 на https://www.cometapi.com/chat/completions
  • Надсилання запиту до фальшивого API-маршруту, такого як 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-тілом запиту розміром 8 MiB, тому старе пояснення, що prompt був надто довгим, було надто вузьким. Якщо ви все ж бачите 413, спочатку розглядайте це як проблему розміру запиту. Поширені підозрювані причини:
  • Великі payload-и у base64
  • Завеликі зображення або аудіо, вбудовані inline
  • Дуже великі multipart- або JSON-тіла
Що робити:
  1. Зменште розмір або стисніть вкладений вміст.
  2. Розбийте великі завдання на менші запити.
  3. Не припускайте, що єдиною причиною є лише довжина звичайного тексту.

​
429 Too Many Requests

Ми не відтворили 429 під час обмеженої перевірки конкурентності з 24 паралельними запитами GET /v1/models, тому точний поріг явно залежить від маршруту, моделі та поточного стану платформи. Сприймайте 429 як помилку, яку можна повторити:
  1. Використовуйте exponential backoff із jitter.
  2. Зменште пікову конкурентність.
  3. Тримайте логування запитів увімкненим, щоб бачити, який маршрут і модель першими досягають насичення.
Для повторно використовуваного шаблону повторних спроб дивіться приклад backoff на сторінці Chat Completions.

​
500, 503, 504, І 524

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

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

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