---
title: Ошибки
description: Единый формат ошибок Clipia API — поля type, code и message, таблица HTTP-статусов и кодов, какие ошибки повторять и как читать уточнение в message.
icon: TriangleAlert
---

Все ошибки REST API приходят в одном формате: объект `error` с полями `type`, `code` и `message`. HTTP-статус задаёт класс ошибки, `code` — машиночитаемую причину. Повторять с паузой имеет смысл только временные ошибки: `409 request_in_progress`, `429`, `500` и `503`.

```json
{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "Недостаточно кредитов. Пополните баланс, чтобы продолжить."
  }
}
```

Ветвите логику по `code`. Поле `message` предназначено для человека и может меняться. Для `400 invalid_request` в `message` лежит уточнение — короткий идентификатор вроде `prompt_required` или `webhook_url_invalid`; полный список для отправки генерации — на странице [«Постановка генерации»](/ru/docs/api-reference/submit#submit-errors). Большинство сообщений приходит на английском, но часть отказов проверки входа (например, слишком короткий промпт или несовместимые референсы) приходит на русском независимо от заголовка. У ошибок `402` и отказов по настройкам музыки заголовок `Accept-Language: ru` переключает текст на русский.

Иногда в `error` есть поля `retry_after_ms` или `retry_after_seconds` — подсказка, через сколько повторить.

Тот же формат у ответов, до обработчика маршрута не дошедших: `400 invalid_request` на тело, которое не разбирается как JSON, `415 unsupported_media_type` на тип тела, который сервер не разбирает (например, `application/xml`), `413 request_too_large` на тело больше 10 МБ и `404 not_found` на неизвестный путь под `/v1/` (включая preflight `OPTIONS` с неразрешённого origin). Внутренние пути сервера в этих ответах не раскрываются.

## Коды

| HTTP | `code` | `type` | Когда | Повторять |
|------|--------|--------|-------|-----------|
| `400` | `invalid_request` | `invalid_request_error` | неверное тело, параметры или идентификатор; причина в `message` | нет, исправьте запрос |
| `401` | `invalid_api_key` | `authentication_error` | ключа нет, он неверный, отозван или истёк | нет |
| `402` | `insufficient_credits` | `billing_error` | не хватает кредитов | после пополнения |
| `402` | `subscription_required` | `billing_error` | нужна активная подписка: условие публичного API на боевом ключе или кредиты заморожены до продления тарифа | после оформления тарифа |
| `402` | `insufficient_quota` | `billing_error` | запрос не укладывается в бюджет ключа, см. [«Управление ключами»](/ru/docs/api-reference/keys) | когда бюджет освободится |
| `403` | `insufficient_scope` | `permission_error` | у ключа нет нужного права | нет |
| `404` | `not_found` | `invalid_request_error` | нет такой модели (`model_not_found`) или запроса (`request_not_found`) | нет |
| `409` | `idempotency_key_reuse` | `idempotency_error` | тот же `Idempotency-Key` с другим телом | нет, смените ключ |
| `409` | `request_in_progress` | `idempotency_error` | повтор, пока первый запрос ещё обрабатывается | да, через несколько секунд |
| `422` | `model_input_invalid` | `invalid_request_error` | параметры не подходят модели | нет, исправьте `input` |
| `429` | `rate_limit_exceeded` | `rate_limit_error` | превышен лимит запросов | да, после `Retry-After` |
| `429` | `concurrency_limit_exceeded` | `rate_limit_error` | превышен лимит одновременных генераций, если он задан; `retry_after_seconds: 5` и `Retry-After: 5` | да, когда завершится одна из задач |
| `500` | `internal_error` | `api_error` | внутренняя ошибка | да, с растущей паузой |
| `503` | `service_unavailable` | `api_error` | сервис временно недоступен | да, с растущей паузой |

Ошибки [AI Gateway](/ru/docs/llm-gateway) (`/v1/chat/completions` и соседние) приходят в формате OpenAI, их коды описаны на странице [«Chat Completions»](/ru/docs/llm-gateway/chat-completions).

<Callout type="warn" title="Боевой ключ требует активной подписки">
Генерация по ключу `clipia_live_` доступна, только пока у аккаунта активна подписка на clipia.ai; тестовый ключ `clipia_test_` работает без оплаты. Без подписки отправка возвращает `402 subscription_required`: покупка пакета кредитов без подписки доступ не открывает, нужен тариф. Проверить состояние заранее: [`GET /v1/account`](/ru/docs/api-reference/account) показывает баланс, а `402` на [оценке стоимости](/ru/docs/api-reference/estimate) не возникает — она считает цену без проверки оплаты.
</Callout>

<Callout type="info" title="Два ответа вне общего формата">
Ответ на тело, которое не разбирается как JSON (`400`), и на несуществующий маршрут (`404`) приходит не в конверте `error`, а в виде `{ "statusCode", "timestamp", "path", "message" }`. Проверяйте HTTP-статус, прежде чем читать `error.code`.
</Callout>

## Повторы

<Callout type="info" title="Что повторять">
`429`, `500` и `503` повторяйте с растущей паузой: 1, 2, 4, 8 секунд, не больше 5 попыток. Для `429` ждите столько, сколько указано в `Retry-After`. Отправку генерации повторяйте с тем же `Idempotency-Key` — так повтор не создаст вторую задачу. Ошибки `4xx`, кроме `409 request_in_progress` и `429`, при повторе без изменений вернутся снова.
</Callout>

<Callout type="warn" title="Без внутренних деталей">
Сообщения ошибок не раскрывают внутреннюю инфраструктуру. Для ошибок `500` и `503` текст общий: «An internal error occurred. Please retry or contact support.» и «Service temporarily unavailable. Please retry later.».
</Callout>

Ошибка самой генерации — не HTTP-ошибка: запрос результата вернёт `200` со `status: "FAILED"` и объектом `error` с кодом из отдельного словаря (`generation_failed`, `content_moderated`, `model_unavailable` и другие), а кредиты вернутся на баланс. См. [«Результат»](/ru/docs/api-reference/result#failed-codes).