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

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

Где читать ошибку

Сценарий	Как определить	Поля
Ошибка запроса в формате OpenAI	HTTP-ошибка или объект ошибки	`error.code`, `error.message`, необязательные `error.param`, `error.type`
Ошибка запроса некоторых API отправки/проверки задач	Проверяйте HTTP-статус и тело	Верхнеуровневые `code`, `message`, `data`
Сбой выполнения задачи	Проверка успешна, но `status` задачи равен `failed`	`error.code`, необязательный `error.reason`, `error.message`
Webhook о сбое задачи	`type` равен `generation.failed`, `data.status` равен `FAILURE`	`data.error.code`, `data.error.message`
Восстановление видеозапроса	Проверяйте `state` записи восстановления	Необязательные `error_code`, `message`, `task_id`

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

{
  "error": {
    "code": "invalid_request",
    "type": "toapis_error",
    "param": "",
    "message": "Image dimensions or aspect ratio do not meet this model's requirements."
  }
}

Пример сбоя выполнения задачи:

{
  "id": "task_example",
  "object": "generation.task",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "reason": "image_dimensions_multiple",
    "message": "Image dimensions must be multiples of 16."
  }
}

Кратность в примере не является общим ограничением моделей. HTTP 200 означает успех проверки, поэтому проверяйте и статус задачи. Числовой бизнес-код code тоже отличается от HTTP-статуса. При success: false проверяйте тело. code идентифицирует ошибку, необязательный reason уточняет причину сбоя задачи, message объясняет ситуацию. error.type не обязательно совпадает с кодом. Текст может зависеть от языка; не стройте логику на полном совпадении сообщений. У некоторых ошибок авторизации code пуст, а некоторые протоколы возвращают только type и message.

Ошибки запросов

Эти идентификаторы возможны в публичных запросах, но не все API возвращают каждый из них. Модель может сохранять исходное написание. Расположение полей указано выше.

Идентификатор	Возможные причины	Действия
`invalid_request`, `invalid_request_error`, `invalid_params`, `InvalidParameter`, `invalid_parameter_error`, `invalid_value`	Неверные типы, размеры изображения, загрузка медиа, структура сообщений или сочетания параметров	Найдите поле через `param` и `message`, затем исправьте входные данные по примерам ниже
`invalid_json`, `invalid_multipart_form`, `read_request_body_failed`	Ошибка разбора JSON/формы или чтения тела	Проверьте сериализацию, `Content-Type` и завершение загрузки
`unknown_parameter`, `unsupported_value`, `provider_capability_not_supported`, `not_supported`	Модель не принимает поле, значение, инструмент или функцию API	Сверьте документацию конкретной модели, уберите неподдерживаемое поле или выберите подходящую модель
`missing_model`, `model_not_found`, `unsupported_model`, `DeploymentNotFound`	Нет имени модели, модель недоступна, API не поддерживается или сервис временно недоступен	Проверьте каталог и права API Key. Если имя верно, а сбой временный, повторите позже или обратитесь в поддержку
`invalid_private_assets`, `invalid_image`, `invalid_image_file`	Неверная ссылка на медиа, ошибка декодирования, превышение количества/размеров или недоступный URL	Проверьте указанный файл и ограничения, экспортируйте или загрузите заново
`access_denied` или HTTP 401/403 без code	API Key неверен, истек, отключен либо ограничен IP или доступ к модели	Проверьте ключ и права. Ошибка авторизации сервиса не всегда означает ошибку вашего ключа
`insufficient_user_quota`, `quota_not_enough`, `token_quota_not_enough`, `pre_consume_token_quota_failed`	Недостаточный баланс, лимит Token или периодический лимит; проверка лимита тоже может временно не работать	Пополняйте баланс или меняйте лимит только при явном указании на ваш аккаунт/Token. При проблемах сервиса повторите позже или обратитесь в поддержку
`rate_limit_exceeded`, `RateLimitReached`, `rate_limit_unavailable`	Ограничение частоты, ограничение сервиса модели или недоступная проверка лимита	Уменьшите параллелизм, соблюдайте `Retry-After`, используйте задержку со случайной составляющей. См. асинхронные лимиты
`get_channel_failed`, `all_channels_circuit_broken`, `provider_unavailable`	Нет доступного сервиса модели или высокая нагрузка	Повторите позже, при повторении обратитесь в поддержку. Менять содержимое изображения не требуется
`do_request_failed`, `first_output_timeout`, `up_timeout`	Тайм-аут соединения, первого вывода или чтения ответа; запрос мог быть принят	Сначала проверьте существующий ID задачи. Для видео без ID используйте восстановление ниже
`bad_response_status_code`, `bad_response`, `bad_response_body`, `read_response_body_failed`, `upstream_error`, `unknown_error`	Ошибка сервиса, чтения или разбора ответа	Учитывайте HTTP-статус и описание, сначала проверьте наличие задачи. При повторении сообщите ID запроса поддержке
`convert_request_failed`, `model_price_error`, `pricing_failed`, `pricing_unavailable`, `internal_error`	Ошибка преобразования запроса, расчета цены или обработки; входные данные не обязательно неверны	Исправьте явно названные ограничения полей, иначе повторите позже или обратитесь в поддержку
`task_not_found`, `task_not_exist`, `request_not_found`	Нет задачи/записи восстановления, ID другого аккаунта или запись истекла	Проверьте ID, аккаунт и API. Отсутствие записи восстановления не доказывает, что исходный запрос не выполнялся
`invalid_client_request_id`, `request_cache_unavailable`, `submission_unconfirmed`	Неверный ID восстановления, сервис недоступен или отправка не подтверждена	Исправьте формат ID либо подождите и проверьте исходный запрос. Не отправляйте подряд с новыми ID
`invalid_callback_url`, `callback_url_origin_mismatch`, `webhook_not_configured`, `webhook_configuration_invalid`, `webhook_configuration_unavailable`, `webhook_configuration_error`, `webhook_api_token_required`	Неверный URL/настройки Webhook у Token или настройки временно недоступны	Проверьте HTTPS, origin, API Token и настройки по руководству Webhook
`sensitive_words_detected`, `prompt_blocked`, `content_policy_violation`, `content_filter`, `content_filtered`	Входные данные или результат не прошли проверку контента	Проверьте промпт и все медиа, исправьте в соответствии с правилами. Не повторяйте автоматически без изменений
`invalid_encrypted_content`	Зашифрованное содержимое элементов ответа диалога не удалось проверить или разобрать	Проверьте, не изменил/обрезал ли клиент прошлые элементы, сохраняйте их без изменений. Не редактируйте шифротекст; при повторении обратитесь в поддержку

Что именно означает invalid_request

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

Ситуация	Как проверить и исправить
Неверный синтаксис размера или соотношения сторон	Некоторые модели принимают в `size` только пропорции вроде `1:1`, другие принимают пиксели. `1024x1024` не подходит модели, ожидающей только пропорции. Следуйте определениям `size`, `resolution`, `aspect_ratio` конкретной модели
Неверные ширина, высота, число пикселей или кратность	Изображение может быть слишком маленьким, большим, широким или не соответствовать кратности. Различайте исходное изображение и размер результата, затем измените размер или обрежьте по ограничениям модели
Превышен размер файла или количество изображений	Байты, длинная сторона, число пикселей и количество файлов ограничиваются отдельно. Сжатие не обязательно уменьшает пиксели. Сжимайте, масштабируйте или уменьшайте количество по сообщению
Неверный тип поля изображения	API, ожидающий массив строк URL, не принимает массив объектов. `image_urls` и `image_with_roles` имеют разную структуру; некоторые API запрещают Base64 или одновременное использование полей
URL существует, но сервис не получает файл	Причины: 403/404, авторизация, истечение URL, тайм-аут, защита прямых ссылок или HTML вместо файла. Передайте публичный URL прямой загрузки с достаточным сроком действия либо используйте API загрузки
Неподдерживаемые формат или длительность	Верное расширение не гарантирует декодирование. GIF, видеокодек, частота кадров, отдельная или суммарная длительность могут нарушать требования. Экспортируйте по документации модели
Тип задачи Seedance конфликтует с параметрами	Для редактирования могут требоваться `aspect_ratio=adaptive`, `duration=-1`, для продления также может требоваться `adaptive`. `InvalidParameter.TaskTypeConstraint` бывает и при распознавании другого типа по промпту и медиа. См. Seedance 2.5
Неверный текст, история диалога или порядок инструментов	Слишком длинный промпт, неподдерживаемая роль `developer`, отсутствие ответов на `tool_calls`, отсутствие `reasoning_content` в режиме размышления. Исправьте историю по протоколу модели
Поле существует, но модель его не принимает	`quality`, `reasoning_effort`, `temperature`, `thinking`, `enable_thinking` не универсальны. `max_tokens` и `max_completion_tokens` могут быть взаимоисключающими. Schema инструментов и `response_format` тоже зависят от модели

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

Причины сбоя задач

После получения ID ориентируйтесь на проверку задачи. Обычная ошибка генерации часто имеет error.code=generation_failed, а необязательный error.reason уточняет категорию. Значения ниже не гарантированы в code ошибок запроса. Если есть error.input_media_errors, читайте type, index, message каждого элемента. Например, type=image, index=0 указывает на первое изображение исходного запроса, чтобы исправить именно его. Эти сведения есть не у всех моделей и форматов проверки.

error.reason	Возможные причины и действия
`invalid_input`, `missing_parameter`	Неверные данные или обязательное поле отсутствует. Проверьте примеры выше и сообщение, затем исправьте запрос
`reference_image_too_large`, `image_dimensions_multiple`	Превышен размер файла исходного изображения или нарушена кратность размеров. Проверяйте байты и пиксели отдельно
`reference_media_unreadable`, `unsupported_media_format`	URL недоступен, файл неверен или формат не поддерживается. Проверьте доступ и фактическое содержимое
`unsupported_parameter_value`, `parameter_out_of_range`, `parameter_replacement_required`	Значение вне допустимого набора/диапазона или требуется заменить поле. Следуйте сообщению и документации модели
`video_edit_parameters_required`, `unsupported_request_capability`	Неверное сочетание параметров редактирования или неподдерживаемая функция. Измените тип, параметры или модель
`content_policy_rejected`	Промпт, исходные изображения/видео/аудио или результат не прошли проверку безопасности/авторских прав. Проверьте все входные данные; допустимый ввод не гарантирует допустимый результат
`service_busy`, `request_rate_limited`	Перегрузка или ограничение частоты. Подождите и снизьте частоту
`generation_timeout`	Тайм-аут генерации или обработки. Проверьте существующую задачу, не создавайте дубликаты обрабатываемых задач
`generation_unavailable`, `model_unavailable`, `model_region_unavailable`	Временная недоступность модели или неподдерживаемый регион. Проверьте модель и права; при повторении обратитесь в поддержку
`insufficient_user_balance`, `token_quota_exceeded`	Недостаточный баланс вашего аккаунта или лимит API Token. Проверьте оба и периодические ограничения
`result_storage_failed`	Сбой сохранения/доставки результата, а не обязательно неподдерживаемый ввод. Сообщите ID задачи поддержке
`submission_pending_reconciliation`	Результат отправки/генерации еще проверяется. Сохраните ID и дождитесь проверки, не создавая дубликаты
`refund_pending`	Возврат по неудачной задаче еще обрабатывается. Проверьте доступные платежные данные новым запросом; при повторении обратитесь в поддержку
`request_cancelled`	Запрос или задача отменены. Убедитесь, что отмена ожидаема, прежде чем отправлять заново
`generation_failed`, `service_error`	Нет более точной публичной причины или произошел внутренний сбой. Сохраните ID задачи/запроса и обратитесь в поддержку

Некоторые модели сохраняют исходные ошибки, например InvalidParameter.TaskTypeConstraint, RateLimitReached, InputImageSensitiveContentDetected, OutputVideoSensitiveContentDetected. Они могут относиться соответственно к параметрам задачи, частоте, проверке входа и проверке результата. Список не исчерпывающий. В Seedance Global поля error.code и error.message могут сохранять исходные JSON-значения, включая числа и null, либо отсутствовать. Формат видео OpenAI и Webhook не гарантируют reason. Обрабатывайте неизвестные коды, пропуски и разные типы; исходный числовой код не является HTTP-статусом.

Повторы и восстановление запросов

Параметры, формат и проверка контента: сначала исправьте ввод. Повтор без изменений обычно не помогает.
Частотные ограничения и временная недоступность: соблюдайте Retry-After, иначе используйте экспоненциальную задержку со случайной составляющей и ограничением повторов.
Есть ID задачи: проверяйте ту же задачу или получайте Webhook. queued и in_progress не являются ошибками и не требуют дубликатов.
Тайм-аут отправки видео или submission_unconfirmed: если исходный запрос использовал client_request_id, вызовите GET /v1/video/requests/{client_request_id} из того же аккаунта. Проверяйте полученный task_id; при submitting или unknown ждите. Только state=failed вместе с error_code=submission_rejected подтверждает отказ и позволяет новый запрос по инструкции. Восстановление доступно только поддерживающим его видео-API при использовании этого поля.

Сбой задачи не означает завершенный возврат. Проверяйте доступные поля billing по руководству оплаты. Отсутствие полей не означает бесплатность или возврат. Webhook является снимком события; платежные поля могут отличаться от последующих проверок.

Обращение в поддержку

Укажите время и часовой пояс, модель, API, HTTP-статус, ID запроса, доступный ID задачи, code/reason и описание без конфиденциальных данных. Для изображения достаточно размеров, формата и размера файла. Не отправляйте API Key, подписанные URL, полные промпты или личные медиа; для воспроизведения используйте минимальный публичный пример.

Обзор

Быстрый старт

Каталог моделей

API чата

API изображений

API видео

API музыки

Управление задачами

Загрузка файлов

Аккаунт

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

Где читать ошибку

Ошибки запросов

Что именно означает invalid_request

Причины сбоя задач

Повторы и восстановление запросов

Обращение в поддержку

​Где читать ошибку

​Ошибки запросов

​Что именно означает invalid_request

​Причины сбоя задач

​Повторы и восстановление запросов

​Обращение в поддержку

Где читать ошибку

Ошибки запросов

Что именно означает invalid_request

Причины сбоя задач

Повторы и восстановление запросов

Обращение в поддержку