Ошибки — Документация Clipia

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

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

Ветвите логику по code. Поле message предназначено для человека и может меняться. Для 400 invalid_request в message лежит уточнение — короткий идентификатор вроде prompt_required или webhook_url_invalid; полный список для отправки генерации — на странице «Постановка генерации». Большинство сообщений приходит на английском, но часть отказов проверки входа (например, слишком короткий промпт или несовместимые референсы) приходит на русском независимо от заголовка. У ошибок 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`	запрос не укладывается в бюджет ключа, см. «Управление ключами»	когда бюджет освободится
`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 (/v1/chat/completions и соседние) приходят в формате OpenAI, их коды описаны на странице «Chat Completions».

Боевой ключ требует активной подписки

Генерация по ключу clipia_live_ доступна, только пока у аккаунта активна подписка на clipia.ai; тестовый ключ clipia_test_ работает без оплаты. Без подписки отправка возвращает 402 subscription_required: покупка пакета кредитов без подписки доступ не открывает, нужен тариф. Проверить состояние заранее: GET /v1/account показывает баланс, а 402 на оценке стоимости не возникает — она считает цену без проверки оплаты.

Два ответа вне общего формата

Ответ на тело, которое не разбирается как JSON (400), и на несуществующий маршрут (404) приходит не в конверте error, а в виде { "statusCode", "timestamp", "path", "message" }. Проверяйте HTTP-статус, прежде чем читать error.code.

Повторы

Что повторять

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

Без внутренних деталей

Сообщения ошибок не раскрывают внутреннюю инфраструктуру. Для ошибок 500 и 503 текст общий: «An internal error occurred. Please retry or contact support.» и «Service temporarily unavailable. Please retry later.».

Ошибка самой генерации — не HTTP-ошибка: запрос результата вернёт 200 со status: "FAILED" и объектом error с кодом из отдельного словаря (generation_failed, content_moderated, model_unavailable и другие), а кредиты вернутся на баланс. См. «Результат».

КодыСкопировать ссылку на раздел

ПовторыСкопировать ссылку на раздел

На этой странице

Коды

Повторы