> ## 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 key отсутствует, имеет неверный формат или недействителен.                                                                       | Нет        | Проверьте `Authorization: Bearer $COMETAPI_KEY`.                                                                        |
| `403`                                    | Доступ был заблокирован или текущий запрос не был разрешён.                                                                          | Обычно нет | Повторите с заведомо корректным запросом и сначала удалите специфичные для модели поля.                                 |
| Ошибка пути                              | Неверный 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 Models page](/ru/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, сохраните его перед обращением в поддержку.

<Warning>
  Если в сообщении упоминаются внутренние термины, такие как `group` или `channel`, считайте их деталями маршрутизации, а не первым, что нужно диагностировать со стороны клиента. Практическое решение по-прежнему состоит в том, чтобы сначала проверить token, model и форму запроса.
</Warning>

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

В Comet ошибка в path может проявляться как:

* Перенаправление
* Не-JSON HTML-ответ, если ваш клиент следует перенаправлениям
* Ошибка парсинга внутри вашего SDK
* Запрос, который так и не доходит до API-уровня корректным образом

Используйте этот base URL без изменений:

```text theme={null}
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. Уменьшите или сожмите прикрепленный контент.
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`, и `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`
* Примерная временная метка
* Работает ли тот же запрос с другой моделью или другим token

Если проблемный маршрут принимает **загрузку файлов** (редактирование изображений, загрузка аудио, генерация видео и т. д.) вместо обычного JSON-тела, отправьте эквивалентный переданный payload:

* Имена полей и текстовые значения, которые вы отправляли вместе с файлом
* Имя файла, тип файла и примерный размер файла
* Был ли файл загружен напрямую, указан по URL или встроен как base64

<Warning>
  Самый эффективный способ воспроизвести баг — это точный очищенный payload запроса. Для большинства API-вызовов это означает **сырой JSON тела запроса**. Для маршрутов с загрузкой файлов — список полей плюс метаданные файла.
</Warning>

Это значительно сокращает время обработки обращения в поддержке.