Ошибки и возвраты

Все ошибки приходят в одном формате. Текст message написан по-русски и его можно показывать пользователю; для логики используйте code.

{
  "error": {
    "code": "invalid_request",
    "message": "Некорректные параметры запроса",
    "request_id": "req_Q2x9…",
    "details": [
      { "field": "resolution", "message": "Допустимо: 1K, 2K, 4K" }
    ]
  }
}

request_id также приходит в заголовке X-Request-Id. Указывайте его при обращении в поддержку.

Коды ошибок запросов

HTTP	code	Что делать
400	`invalid_request`	Исправьте параметры по полю details
400	`invalid_json`	Проверьте, что тело — корректный JSON
400	`mode_not_supported`	Режим видео недоступен для модели
401	`unauthorized / invalid_api_key`	Проверьте ключ
402	`insufficient_balance`	Пополните баланс
402	`daily_limit_exceeded`	Достигнут дневной лимит ключа — увеличьте его в кабинете или дождитесь 00:00 МСК
403	`model_disabled`	Модель временно отключена для API
404	`model_not_found / task_not_found / file_not_found`	Проверьте идентификатор
409	`idempotency_conflict`	Idempotency-Key уже использован с другим телом
409	`task_not_cancellable`	Задача уже в работе или завершена
410	`file_expired`	Загрузите файл заново
413	`payload_too_large`	Уменьшите файл или тело запроса
415	`unsupported_media_type / file_invalid`	Неверный Content-Type или формат файла
429	`rate_limited / queue_full / too_many_files`	Подождите Retry-After секунд
503	`api_disabled / maintenance / model_unavailable`	Временная недоступность — повторите позже
500	`internal_error`	Повторите запрос с тем же Idempotency-Key

Ошибки генерации

Если задача завершилась со статусом failed, в поле error будет причина, а в refund — сколько Мыслей вернулось.

error.code	Причина
`content_policy`	Запрос или изображение нарушают правила контента модели
`timeout`	Модель не ответила вовремя
`provider_error`	Сбой на стороне модели
`no_result`	Модель не вернула результат
`generation_failed`	Прочие ошибки генерации

Правила возвратов

Технический сбой, таймаут, ошибка модели — Мысли возвращаются автоматически.
Срабатывание модерации контента — возможен частичный возврат, как в студии.
Отмена задачи из очереди или истечение ожидания — возврат 100%.

Подробные условия — в правилах возврата.