Обробляти помилки 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.
Не припускайте, що кожен некоректний 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.
- Підтвердьте, що endpoint path точно відповідає документації.
- Вимкніть автоматичне слідування перенаправленням під час налагодження проблем із 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, and 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
- Приблизна часова позначка
- Чи працює той самий запит з іншою моделлю або іншим токеном
Якщо маршрут, що завершується помилкою, приймає завантаження файлів (редагування зображень, завантаження аудіо, генерація відео тощо) замість звичайного JSON-тіла, надішліть еквівалентний переданий payload:
- Назви полів і текстові значення, які ви надсилали разом із файлом
- Назва файлу, тип файлу та приблизний розмір файлу
- Чи було файл завантажено напряму, вказано за URL або вбудовано як base64
Найефективніший спосіб відтворити баг — це точний очищений payload запиту. Для більшості API-викликів це означає сирий JSON тіла запиту. Для маршрутів із завантаженням файлів це означає список полів плюс метадані файлу.
