Ошибки
Каждая ошибка от эндпоинтов 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; эти два случая намеренно неразличимы.
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) не затрагиваются лимитом опроса.