Справочник ошибок

Авторизация

Для отправки запросов нужен API ключ — см. раздел С чего начать?

При успешном ответе HTTP-статус равен 200, а поле code в теле — нулю. При ошибке возвращается соответствующий HTTP-статус, а машиночитаемый код передаётся в поле code.

Формат ответа

{
  "code": 5,
  "message": "Insufficient balance, check account balance.",
  "trace_id": "662f1a9c4b1e2d0012a3b4c5"
}

Поле	Тип	Обяз.	Описание
code	number	да	Код ошибки (0 при успехе, см. таблицу ниже).
message	string	да	Человекочитаемое описание ошибки.
details	array	нет	Детали валидации входных данных (присутствует при code: 3).
trace_id	string	нет	Идентификатор запроса для обращения в поддержку (при внутренних ошибках, code: 1).

Авторизация

Если API-ключ отсутствует или недействителен, возвращается HTTP 401 с телом вида { "error": { "message": "Unauthorized" } }. Проверьте заголовок Authorization.

Доступные ошибки

Code	HTTP	Message
1	500	Internal server error.
3	400	Invalid input, check schema issues.
5	402	Insufficient balance, check account balance.
6	429	API key limit exceeded. Check your daily or monthly limits.
7	403	Model is not available for this account (banned or restricted).
20	404	Model not found or is not available via the LAB API.
21	410	Model is deprecated or not available for this organization.
22	404	Task not found.
23	409	Task with this idempotency_key already exists with different input.
24	404	Model is not available for this API key. Request GET /api/v2/media/models to see the models available to you.
25	400	Input file was rejected by the model. Check its size, format, resolution and aspect ratio.
26	400	Prompt was rejected by the model. Check its length and content.
27	400	Requested combination of parameters is not supported by this model.
28	503	Generation failed for a reason we could not attribute. Repeat the same request later; if it keeps failing, check the input files and their URLs.
99	404	API method not found, check the URL.
1001	400	Sensitive content has been detected in your request or uploaded files. Please check the text and media and try again.
1002	400	Request was blocked by moderation.

Коды 25–28 и 1001–1002 приходят в объекте задачи

Эти причины относятся к результату генерации, поэтому приходят не HTTP-статусом, а в поле error задачи при status: failed — см. Получение задачи. Рядом с code там лежит title — точный машиночитаемый код причины: он детальнее кода и позволяет различать случаи внутри одной группы (например, ERR_IMAGE_TOO_LARGE и ERR_UNSUPPORTED_FILE_FORMAT оба дают code: 25). Новые причины появляются в title без изменения таблицы кодов.

Коды отказа задачи изменились

Раньше причина отказа почти всегда приходила как code: 1 — в каталоге было представлено лишь пять причин из четырёх с лишним десятков, остальные схлопывались во «внутреннюю ошибку». Теперь у отказов есть осмысленные коды 25–28, а точная причина — в поле error.title.

Если вы ветвитесь по error.code при status: failed, проверьте обработчики: часть отказов, ранее приходивших как 1, теперь приходит с кодами 25–28, 1001 или 1002. Отдельно поменялись три причины, у которых код был взят из нумерации v1 и в контракте v2 означал другое:

• перегрузка провайдера: было 6 — в v2 этот код означает «превышен лимит ключа», — стало 28;
• требуется входное изображение: было 400, кода с таким номером в v2 нет вовсе, — стало 25;
• модель не поддерживает пару кадров: было 400 — стало 27.

Код 1 остался за тем, чем и должен быть, — за неопознанным сбоем на нашей стороне. Для точной обработки используйте error.title: он не меняется при добавлении новых причин.

Ошибка 21

Приходит, когда провайдер снял модель с обслуживания и аналог для неё не назначен, либо модель закрыта для вашей организации. Если аналог есть, задача создаётся на нём и этой ошибки не будет. В теле дополнительно приходит original_id — id запрошенной модели:

{
  "code": 21,
  "message": "Model is deprecated or not available for this organization.",
  "original_id": "kling-v2"
}

Подробнее — в разделе Устаревшие модели.

Заметка

Ошибка code: 23 возникает, когда idempotency_key уже использован для другого запроса — используйте новый ключ либо повторите исходный запрос без изменений.