> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Ошибки API, причины сбоя задач, исправление входных данных и восстановление неопределенных отправок

Сначала различайте ошибку запроса и сбой задачи генерации. `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` |

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

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

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

```json theme={null}
{
  "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 не поддерживается или сервис временно недоступен | Проверьте [каталог](https://docs.toapis.com/docs/ru/api-reference/models.md) и права 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`, используйте задержку со случайной составляющей. См. [асинхронные лимиты](https://docs.toapis.com/docs/ru/api-reference/rate-limits/async-tasks.md) |
| `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](https://docs.toapis.com/docs/ru/api-reference/webhooks/task-webhooks.md) |
| `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 загрузки](https://docs.toapis.com/docs/ru/api-reference/uploads/images.md) |
| Неподдерживаемые формат или длительность | Верное расширение не гарантирует декодирование. GIF, видеокодек, частота кадров, отдельная или суммарная длительность могут нарушать требования. Экспортируйте по документации модели |
| Тип задачи Seedance конфликтует с параметрами | Для редактирования могут требоваться `aspect_ratio=adaptive`, `duration=-1`, для продления также может требоваться `adaptive`. `InvalidParameter.TaskTypeConstraint` бывает и при распознавании другого типа по промпту и медиа. См. [Seedance 2.5](https://docs.toapis.com/docs/ru/api-reference/videos/seedance-2-5/generation.md) |
| Неверный текст, история диалога или порядок инструментов | Слишком длинный промпт, неподдерживаемая роль `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](https://docs.toapis.com/docs/ru/api-reference/webhooks/task-webhooks.md). `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` по [руководству оплаты](https://docs.toapis.com/docs/ru/api-reference/account/pricing.md). Отсутствие полей не означает бесплатность или возврат. Webhook является снимком события; платежные поля могут отличаться от последующих проверок.

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.