> ## 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 з помилками та застосовувати повторні спроби або кроки виправлення для поширених збоїв запитів.
Обробляти помилки CometAPI найпростіше, якщо розділяти **проблеми форми запиту**, **проблеми автентифікації**, **помилки шляху** та **збої платформи, які можна повторити**. Використовуйте поєднання HTTP-статусу, `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 і збережіть id запиту. |
## Структура помилки
Багато збоїв CometAPI використовують тіло помилки такого вигляду:
```json theme={null}
{
"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.
Використовуйте такий мінімальний запит:
```json theme={null}
{
"model": "your-model-id",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}
```
Замініть `your-model-id` на будь-який поточний model ID зі [сторінки моделей CometAPI](/uk/overview/models).
Не припускайте, що кожен некоректний chat-запит повертає `400`. Відсутність обов’язкових chat-полів, таких як `messages`, також може проявлятися як `500` з `error.code: invalid_request`.
## `500 Internal Server Error`
Більшість відповідей `500` вказують на збій платформи або провайдера. Для Chat Completions деякі некоректні запити також можуть проявлятися як `500`, водночас містячи `error.code: invalid_request`.
Один із прикладів — запит, у якому пропущено `messages`:
```json theme={null}
{
"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 зазвичай виглядає так:
```json theme={null}
{
"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 не має права використовувати запитану model або форму запиту
* Вибрана model відхиляє один із переданих вами розширених параметрів
Що зробити спочатку:
1. Повторіть запит із дуже простим текстовим запитом до завідомо робочої model.
2. Приберіть розширені поля та provider-specific параметри, а потім поступово додавайте їх назад.
3. Якщо відповідь містить request id, збережіть його перед зверненням до підтримки.
Якщо в повідомленні згадуються внутрішні терміни, такі як `group` або `channel`, сприймайте їх як деталі маршрутизації, а не як перше, що слід діагностувати з боку клієнта. Практичне виправлення все одно полягає в тому, щоб спочатку перевірити token, model і форму запиту.
## Неправильний base URL або неправильний path
У Comet помилка в path може проявлятися так:
* Перенаправлення
* Не-JSON HTML-відповідь, якщо ваш клієнт слідує перенаправленням
* Помилка парсингу всередині вашого SDK
* Запит, який так і не доходить до API-рівня належним чином
Використовуйте цей base URL без змін:
```text theme={null}
https://api.cometapi.com/v1
```
Рекомендовані перевірки:
1. Підтвердьте, що base URL містить `/v1`.
2. Підтвердьте, що endpoint path точно відповідає документації.
3. Вимкніть автоматичне слідування перенаправленням під час налагодження проблем із path.
## `413 Request Entity Too Large`
Якщо ви бачите `413`, насамперед розглядайте це як проблему **розміру запиту**. Типові підозрювані:
* Великі payload у форматі base64
* Завеликі зображення або аудіо, вбудовані inline
* Дуже великі multipart або JSON body
Що робити:
1. Зменште або стисніть вкладений вміст.
2. Розбийте великі завдання на менші запити.
3. Не припускайте, що єдиною причиною є лише довжина звичайного тексту.
## `429 Too Many Requests`
Сприймайте `429` як помилку, яку можна повторити:
1. Використовуйте exponential backoff з jitter.
2. Зменште burst concurrency.
3. Не вимикайте логування запитів, щоб бачити, які route і model першими досягають насичення.
Для шаблону повторних спроб, який можна використовувати повторно, див. приклад backoff у [Chat Completions](/api/text/chat).
## `503`, `504`, and `524`
Ці статуси є **збоями на боці сервера або збоями класу timeout**.
Практичні орієнтири:
* `503`: route або provider service тимчасово недоступний
* `504` і `524`: збої класу timeout між платформою, edge або provider service
Що робити:
1. Повторюйте запит із backoff.
2. Зберігайте `request id`, endpoint, model і часову мітку.
3. Якщо той самий збій повторюється в кількох спробах, зверніться до підтримки з цим контекстом.
## Перед тим як звертатися до підтримки
Спочатку зберіть ці дані:
* HTTP-метод
* Шлях endpoint
* model ID
* **Очищений JSON тіла запиту** (це найкорисніший елемент для більшості API-викликів)
* Параметри запиту, якщо запит, що завершився помилкою, їх використовував
* Точне тіло відповіді, якщо ваш клієнт його зафіксував
* Повний HTTP-статус
* Точний `error.message`
* Будь-який `request id`
* Приблизна часова позначка
* Чи працює той самий запит з іншою моделлю або іншим токеном
Якщо маршрут, що завершується помилкою, приймає **завантаження файлів** (редагування зображень, завантаження аудіо, генерація відео тощо) замість звичайного JSON-тіла, надішліть еквівалентний переданий payload:
* Назви полів і текстові значення, які ви надсилали разом із файлом
* Назва файлу, тип файлу та приблизний розмір файлу
* Чи було файл завантажено напряму, вказано за URL або вбудовано як base64
Найефективніший спосіб відтворити баг — це точний очищений payload запиту. Для більшості API-викликів це означає **сирий JSON тіла запиту**. Для маршрутів із завантаженням файлів це означає список полів плюс метадані файлу.
Це значно скорочує час обробки звернення підтримкою.