Ошибки

Каждая ошибка от эндпоинтов Video API использует одну и ту же JSON-форму:


{
  "error": {
    "code": "...",
    "message": "..."
  }
}

HTTP-статус сообщает класс проблемы; error.code — стабильная строка, по которой можно ветвить код. Всегда сопоставляйте по error.code, а не парсите error.message.

Коды ошибок

HTTP	Code	Значение
400	`invalid_request`	Отсутствует обязательный параметр или значение недействительно
400	`invalid_callback_url`	`callback_url` не HTTPS или указывает на приватную сеть (заблокировано SSRF-проверками)
400	`references_conflict`	`frame_images` и `input_references` отправлены в одном запросе (взаимоисключающие)
400	`too_many_references`	`input_references` превышает лимиты (изображения > 9 / аудио > 3 / видео > 1)
400	`cancel_not_supported`	Upstream-провайдер не может прервать эту задачу
400	`cancel_failed`	Задача уже в конечном состоянии и не может быть отменена
401	`unauthorized` / `invalid_api_key`	Аутентификация не удалась
401	`upstream_auth_failed`	Аутентификация у upstream-провайдера не удалась
402	`insufficient_credits`	Недостаточно баланса для принятия задачи
404	`not_found`	Задача не существует или у вас нет к ней доступа
404	`model_not_found`	Запрошенная модель не существует
429	`rate_limited`	Слишком много запросов (лимит опроса или upstream-лимит)
502	`upstream_error` / `route_error`	Ошибка upstream-провайдера / сбой маршрутизации
500	`internal_error`	Неожиданная внутренняя ошибка

references_conflict и too_many_references — ошибки валидации body запроса; точные лимиты см. в Создании видео. cancel_not_supported и cancel_failed описаны в Отмене видео. not_found возвращается и для неизвестной задачи, и для задачи, принадлежащей другому API key; эти два случая намеренно неразличимы.

Ошибки предобработки `real_person`

Если предобработка изображения с real_person: true завершается ошибкой из-за переданного изображения, API возвращает HTTP 400 с error.code: "invalid_request". В конце error.message указан один из следующих стабильных кодов причины и позиция ошибочного референса, например input_references[0]:

Код причины	Что исправить
`bad_data_uri`	URI `data:` имеет неверный формат или содержит недопустимые данные base64
`download_failed`	Изображение не удалось скачать из-за соединения, таймаута или ограничения доступа
`unreachable`	URL изображения вернул HTTP-статус ошибки
`not_image`	Скачанное содержимое не является поддерживаемым декодируемым изображением
`too_large`	Изображение превышает лимит размера, пикселей или обработки на один запрос


{
  "error": {
    "code": "invalid_request",
    "message": "real_person image processing failed — input_references[0]: ... (not_image)"
  }
}

В логике приложения продолжайте ветвление по error.code. Код причины и позицию референса используйте для исправления входных данных или диагностики.

402 Недостаточно кредитов

insufficient_credits возвращается только при создании задачи (POST /v1/videos). Когда предварительная авторизация включена, ofox до принятия задачи оценивает стоимость по запрошенным разрешению и длительности. Если оценка превышает ваш баланс, запрос сразу отклоняется — запись о задаче не создается и списаний нет.


{ "error": { "code": "insufficient_credits", "message": "..." } }

insufficient_credits — единственный код 402, который возвращает Video API. Обработайте этот один код, пополните баланс и повторите попытку.

429 Лимит запросов

rate_limited покрывает как лимит опроса на ключ для GET /v1/videos/{id}, так и upstream-лимиты. Когда вы достигаете лимита опроса, ответ содержит заголовок Retry-After:


HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": { "code": "rate_limited", "message": "..." } }

Учитывайте заголовок Retry-After и сделайте паузу перед повтором. Если вы часто опрашиваете, переключитесь на webhook-уведомления, чтобы ofox сам отправлял вам конечное состояние — это полностью обходит лимит опроса. Создание задачи (POST) и отмена (DELETE) не затрагиваются лимитом опроса.