Коды ошибок API text-to-video: подробное объяснение

Большинство сбоев API text-to-video сводятся к 5 категориям: некорректные запросы, проблемы с аутентификацией, лимиты запросов, блокировки безопасности или проблемы на сервере. Если я проверяю HTTP-статус, полное тело ошибки, ID запроса или задачи и время сбоя, я обычно быстро нахожу причину.

Вот краткая версия:

• Ошибки 400-й серии обычно означают, что мне нужно исправить запрос.
• 401/403 обычно указывают на API-ключ, доступ, биллинг или правила по IP.
• 429 означает, что я достиг лимита по запросам, задачам или расходам.
• 200 OK при отправке не означает, что видео готово. Мне всё равно нужно опрашивать задачу и проверять failed.
• Ошибки 500-й серии часто требуют повтора, но только после того, как я проверю, выполняется ли ещё задача.
• Блокировки безопасности могут происходить до, во время или после генерации, и некоторые API могут возвращать меньше клипов вместо провала всей задачи.

Несколько цифр стоит выделить. Задачи по генерации видео, например использующие Sora 2, могут удерживать GPU 30–90 секунд, клиентские таймауты могут требовать 10+ минут, а типичный план повторов — начать с 5 секунд, ограничить 60 секундами, остановиться после 3 попыток.

Если я хочу меньше проваленных задач и меньше дублирующихся списаний, я держу рабочий процесс простым:

• Логирую тело ошибки и ID задачи
• Разделяю ошибки уровня API и сбои уровня задачи
• Повторяю только случаи 429 и 5xx
• Проверяю состояние задачи, прежде чем отправлять ту же задачу снова
• Фиксирую точные версии моделей вместо алиасов вроде latest

Сообщения об ошибках API для ХОРОШЕГО опыта разработчика

Быстрое сравнение

Проще говоря: успешная отправка — это не успешный рендер. Я бы считал результаты опроса источником истины и использовал бы содержимое ошибки — а не только код статуса — чтобы решить, что делать дальше.

Ошибки запросов на стороне клиента: коды 400-й серии, которые вы можете исправить

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

400, 404, 413 и 415: что каждый код означает для видеозапросов

Каждый код указывает на свой тип ошибки в запросе. 400 обычно означает некорректный JSON, отсутствие обязательных полей или неверные типы параметров. Например, передача duration как строки ("6") вместо целого числа (6) не пройдёт валидацию ^[4]. 404 означает, что неверен ID модели или путь эндпоинта, часто из-за небольшой опечатки вроде wan2.7 вместо [wan-2.7](https://apimart.ai/ja/model/wan-2-7) или [wan-2.6](https://apimart.ai/model/wan-2-6) ^[7]. 413 возникает, когда референсное изображение или видео превышает лимит размера загрузки ^[4][7]. 415 означает, что заголовок Content-Type неверен или формат файла не поддерживается моделью ^[5].

Несоответствия модели и параметров, вызывающие сбои валидации

Даже когда ваш JSON корректен, запросы всё равно могут не пройти валидацию, потому что модели не следуют одинаковым правилам. Разрешение, длительность, соотношение сторон и лимиты ассетов могут отличаться от модели к модели.

Возьмём MiniMax-Hailuo-2.3. Она поддерживает 10 секунд при 768p, но если вы запросите 1080p, максимальная длительность снижается до 6 секунд ^[6]. Правила по ассетам могут быть не менее строгими. Kling 3.0 требует, чтобы входные изображения были не менее 300 px по обоим измерениям, с соотношением сторон между 1:2.5 и 2.5:1. Wan 2.7 требует, чтобы референсные видео были длиной 2–10 секунд и не больше 100 MB ^[4][7].

422 обычно означает, что ваши параметры конфликтуют друг с другом. Например, SkyReels V4 возвращает 422, когда вы комбинируете поля Image-to-Video и Omni в одном запросе ^[8].

Одна небольшая привычка может сэкономить много времени: используйте зафиксированные строки версий вместо общих алиасов. Правила по параметрам могут меняться между версиями модели ^[3]. Если валидация всё равно не проходит, проверьте точные лимиты модели, прежде чем повторять.

Если запрос проходит валидацию, но всё равно завершается сбоем, переходите к аутентификации, лимитам запросов и проверкам безопасности.

Аутентификация, разрешения и лимиты запросов

Как только валидация пройдена, большинство оставшихся сбоев сводятся к трём вещам: аутентификация, разрешения или лимиты запросов.

401 и 403: ошибки API-ключа и доступа

Ошибка 401 Unauthorized означает, что запрос не содержал действительных учётных данных для аутентификации. Обычные причины — отсутствующий API-ключ, недействительный ключ, ключ, который был отключён или удалён, или сломанный заголовок Authorization ^[9][1][2].

Многие API ожидают:

Authorization: Bearer YOUR_API_KEY

Некоторые платформы используют x-api-key вместо этого. Так что если имя или формат заголовка неверны, одно это может вызвать 401 ^[1][10].

Начните с основ. Проверьте переменную окружения, убедитесь, что ключ ещё активен, и подтвердите, что ваша настройка CI/CD корректно внедряет секреты в каждом окружении ^[3]. Также полезно читать тело ответа, а не останавливаться на HTTP-коде статуса. Ошибки вроде invalid_api_key, token_expired или account_banned обычно гораздо быстрее подсказывают, что сломалось ^[9][3].

403 Forbidden означает, что сервер вас распознал, но всё равно заблокировал запрос. Это обычно указывает на проблему с доступом. У вашего ключа может не быть нужного scope модели, ваш тарифный план может не включать этот эндпоинт, ваши кредиты могут быть исчерпаны, или IP вашего запроса может быть не в списке разрешённых ^[3][9].

Тело ответа тоже важно здесь. Если вы видите insufficient_credits, посмотрите на биллинг. Если вы видите permission_error, проверьте scopes, доступ к модели или лимиты плана. А если с доступом всё в порядке, но трафик слишком высок, следующая остановка обычно 429.

429: ошибки превышения лимита запросов и квоты

Если аутентификация проходит, объём запросов часто становится следующим узким местом. Ошибка 429 Too Many Requests означает, что вы достигли ограничения по частоте, лимита параллелизма или лимита расходов ^[3][9][10]. Проще говоря: вы отправили слишком много запросов за короткий промежуток, запустили слишком много задач одновременно или пересекли биллинговый лимит ^[3][9].

Опять же, тело ответа даёт лучшую подсказку. rate_limit_exceeded обычно означает, что вам следует использовать экспоненциальный backoff. spend_limit_exceeded означает, что пора проверить настройки биллинга ^[3][9].

Ставьте пакетные задачи в очередь локально, когда можете, и следите за этими заголовками ^[2]:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Если вы используете APIMart, один ключ на все модели может уменьшить рассинхронизацию аутентификации ^[3]. Даже тогда процесс отладки остаётся примерно тем же: читайте тело ответа, проверяйте переменные окружения и убедитесь, что аккаунт может получить доступ к вызываемой модели.

Блокировки безопасности, таймауты и сбои на стороне сервера

После прохождения валидации запроса и аутентификации оставшиеся сбои обычно делятся на две категории: блокировки модерации и проблемы на стороне сервера. Так что как только аутентификация, квота и валидация пройдены, разделите оставшуюся отладку на эти два пути.

Ошибки модерации и политики контента при генерации видео

Блокировки безопасности могут происходить в трёх разных точках: до начала генерации (запрос отклоняется сразу), во время рендеринга (задача останавливается на полпути) или после того, как видео создано (результат фильтруется перед доставкой) ^[11]. Именно последний случай сбивает людей с толку. Задача может завершиться и всё равно ничего не доставить, если результат отфильтрован.

С API на основе опроса HTTP-статус может вводить в заблуждение. Вы можете получить 200 OK от проверки статуса, тогда как тело JSON говорит state: "failed" и включает ошибку вроде SensitiveContentDetected или NSFW ^[12]. На практике тело опроса — это источник истины, а не HTTP-код статуса.

Если сработала блокировка модерации, не повторяйте тот же самый промпт. Перепишите его. Простые технические формулировки в стиле кинематографии могут помочь снизить количество ложных срабатываний строгих фильтров безопасности ^[11]. Например:

• gimbal shot
• medium tracking shot
• golden hour lighting

Здесь есть ещё один нюанс. Некоторые модели, включая Google Veo, могут возвращать меньше клипов, чем вы запросили, когда часть выходных данных заблокирована фильтрами безопасности, вместо провала всей задачи ^[3]. Так что не просто проверяйте, завершился ли запрос. Проверьте, что число возвращённых ассетов совпадает с числом, которое вы запросили.

Если промпт выглядит корректно, а задача всё равно проваливается, переходите к следующему слою: стабильность сервера.

Ошибки 500, 502, 503 и таймаута для асинхронных видеозадач

Сбои на стороне сервера находятся в другой части процесса отладки. Задачи text-to-video часто удерживают слот GPU 30–90 секунд ^[3], что делает их более чувствительными к перегрузкам и таймаутам.

Для ошибок 500 и 504 проверяйте статус задачи, прежде чем повторять. Слепые повторы могут создать дублирующиеся рендеры и удвоить ваши расходы ^[3]. Логируйте каждый taskId или prediction_id, чтобы вы могли напрямую запросить эндпоинт статуса перед отправкой новой задачи ^[3][13].

Когда повторы безопасны, используйте экспоненциальный backoff с джиттером. Практичная настройка:

• начать с 5 секунд
• ограничить 60 секундами
• остановиться после 3 попыток ^[13][12]

Установите клиентские таймауты в 10 минут или больше ^[3] и настройте оповещения на растущие значения predict_time ^[3].

Пошаговый процесс отладки для API text-to-video

Классифицируйте ошибку, затем примените правильное исправление

Используйте этот процесс, чтобы пройти путь от симптома к исправлению за один проход. Сначала прочитайте полное тело ответа. Затем отсортируйте сбой по HTTP-коду статуса и тому, что говорит тело ошибки. Некоторые провайдеры также присылают внутренние диапазоны ошибок, но вашим главным ориентиром должны быть HTTP-код статуса и тело ошибки ^[3][1].

Начните с тела ответа, затем отнесите результат к одной из этих групп:

Как только задача отправлена, перестаньте мыслить только в терминах HTTP-ответов и посмотрите также на состояние задачи. Для асинхронных задач проверяйте ответ опроса на failed или expired, прежде чем отправлять ту же задачу снова. Один этот шаг может уберечь вас от лишних затрат и большой путаницы.

Прежде чем трогать код, проверьте страницу статуса провайдера. Если сервис деградирован, локальная отладка мало что вам скажет. После этого изучите заголовки ответа x-deny-reason. Отказы на уровне прокси могут выглядеть как ошибки модели, если пропустить эту проверку ^[3].

Также фиксируйте точные строки версий модели, например kling-v3.0-std, вместо latest. Незаметное обновление модели может внести новые сбои валидации в пайплайн, который отлично работал днём ранее ^[3].

Ключевые выводы для более надёжных интеграций

Большинство сбоев API text-to-video следуют нескольким повторяющимся шаблонам. Если вы получаете ошибку 4xx, вам нужно изменить запрос, учётные данные или настройку. Повторная отправка того же вызова обычно ничего не исправит.

• Логируйте входные данные запроса: ID модели, хэш промпта и параметры (см. наши руководства по AI API о лучших практиках логирования).
• Логируйте ID задачи, финальный статус, predict_time и полное сообщение об ошибке.
• Повторяйте только 429 и 5xx после проверки состояния задачи, чтобы избежать дублирующихся рендеров и удвоенных затрат ^[3].
• Следите за всплесками predict_time — они могут заранее сигнализировать о деградации инфраструктуры ^[3].

Часто задаваемые вопросы

Как узнать, действительно ли видеозадача провалилась?

Опросите эндпоинт статуса задачи с ID задачи, который вы получили при её отправке. Если поле status возвращается как failed, задача не прошла.

Далее посмотрите на поле error в ответе. Оно говорит вам, почему она провалилась, чтобы вы могли решить, что делать дальше:

• скорректировать ваш промпт
• проверить баланс аккаунта
• подождать, если есть проблема с инфраструктурой

Вы также можете использовать вебхуки, чтобы получать автоматические уведомления, когда задача переходит в состояние failed.

Когда следует повторять запрос к API text-to-video?

Повторяйте временные ошибки вроде лимитов запросов 429 и серверных проблем 500 с экспоненциальным backoff. Это замедляет повторные попытки и помогает избежать перегрузки системы.

Для 504 Gateway Timeout или сбоя задачи проверьте статус задачи, прежде чем пробовать снова. Слепой повтор может вызвать дублирующиеся рендеры и добавить лишние затраты.

Не повторяйте ошибки 400 или 401. Они обычно означают, что сначала нужно исправить сам запрос.

Почему промпт может быть заблокирован после отправки?

Промпт обычно блокируется, потому что он нарушает правила безопасности или модерации провайдера. Это может произойти прямо при отправке или позже, во время генерации, если система обнаруживает запрещённый визуальный или аудиоконтент.

Частые триггеры включают чувствительные темы, насилие, несовершеннолетних или материалы, защищённые авторским правом. И поскольку системы модерации склонны перестраховываться, даже безобидные промпты могут быть помечены.

Если это происходит, перепишите запрос более нейтральным, описательным языком.