Ошибка TASK_FAILED при возврате задачи HiAPI: причины и способы исправления

При отправке асинхронной задачи в API задач HiAPI успешная отправка возвращает HTTP 200 и taskId. Затем задача выполняется в фоне, и когда вы опрашиваете её статус, она может завершиться в терминальном состоянии fail. В этом случае ответ на опрос выглядит примерно так — обратите внимание, что сам HTTP-вызов по-прежнему 200:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M4RK...",
    "model": "seedream-5.0-lite/image-to-image",
    "status": "fail",
    "error": { "code": "TASK_FAILED", "message": "task failed" },
    "created": 1791827316,
    "completed": 1791827352,
    "storage": "temp"
  },
  "message": "success"
}

Это то, что обычно называют «ошибкой TASK_FAILED»: запрос принят, задача выполнена, но завершилась неудачно. Это не ошибка HTTP 4xx и не тайм-аут. В этой статье мы научим вас читать такой ответ и устранять каждую из причин по очереди.

Сначала уясните: TASK_FAILED — это не HTTP-статус

Самое важное для понимания:

• HTTP-статус вызова опроса — 200, в теле ответа даже указано "message": "success" — это означает лишь успешность вызова API, а не успешность вашей задачи.
• "status": "fail" (внутри data) — это основание считать задачу неуспешной. Для завершённой задачи data.status может быть только "success" или "fail".
• "TASK_FAILED" — это значение data.error.code, а не status. Некоторые сбои сопровождаются более конкретным кодом и более информативным сообщением (см. ниже).

Поэтому всегда опрашивайте GET /v1/tasks/{taskId} и принимайте решения на основе data.status, никогда не определяйте успех или неудачу только по HTTP-статусу.

Определение причины по деталям задачи

Получив терминальный ответ, читайте поля data в следующем порядке:

1. Сначала посмотрите data.status — задача считается неуспешной только если это "fail".
2. Затем прочитайте data.error.code — это машиночитаемая категория ошибки (например, TASK_FAILED, INVALID_REQUEST, CONTENT_POLICY_VIOLATION).
3. Наконец, прочитайте data.error.message — это пояснение для человека, обычно прямо указывающее на причину (например, недоступность какого-то входного URL).

error.code в основном определяет, «можно ли решить этот сбой повторной попыткой»: обобщённый TASK_FAILED (сообщение обычно "task failed") часто является кратковременным сбоем и может быть повторён; ошибки с явным кодом (например, INVALID_REQUEST, CONTENT_POLICY_VIOLATION) являются детерминированными сбоями — сколько бы раз вы ни повторяли без изменения входных данных, результат будет тем же.

Распространённые причины терминального fail

Примерно в порядке убывания частоты.

1. URL входного изображения / видео недоступен или не является публичным

Это самая частая причина для задач image-to-image и image/video-to-video. Если ваш input ссылается на URL, который платформа не может получить, задача будет принята, но завершится сбоем при выполнении. Реальный терминальный ответ:

"error": {
  "code": "INVALID_REQUEST",
  "message": "The image URL could not be downloaded. Please provide a reachable public HTTP(S) URL and try again."
}

Здесь message уже всё ясно говорит. Другие модели могут раскрывать ту же первопричину как обобщённый TASK_FAILED / "task failed".

Исправление: разместите входные данные на публично доступном HTTPS URL и проверьте до отправки:

curl -I "https://your-host.example.com/input.png"
# Должен вернуть 200 и прямой content-type медиафайла (image/* или video/*)
# Не должен быть 401/403/404 и не должен быть HTML-страницей

Просроченные предподписанные URL, адреса localhost / внутренней сети, ссылки, требующие входа, — самые частые подводные камни. Это детерминированные сбои — если не исправить URL, повторная попытка лишь снова впустую прогонит задачу.

2. Кратковременный сбой или сбой генерации на стороне вышестоящего сервиса

Иногда полностью корректная по формату задача завершается с обобщённым error.code: "TASK_FAILED", message: "task failed" и без дополнительных деталей. Это чаще всего кратковременный сбой.

Исправление: повторите попытку один-два раза. Если с теми же входными данными сбой повторяется, упростите входные данные (сократите prompt, уберите необязательные поля) и запустите снова, чтобы сузить областьtriggerа.

3. Контент заблокирован политикой безопасности

Если prompt или входное изображение нарушают политику безопасности контента платформы, задача завершится детерминированной ошибкой политики, data.error.code будет CONTENT_POLICY_VIOLATION.

Исправление: это постоянный сбой, повторные попытки бесполезны. Измените prompt и входные материалы, уберите нарушающий контент и отправьте заново.

4. Параметр, который модель отклоняет только во время выполнения

Большинство недопустимых параметров блокируются уже при отправке с HTTP 400 (вы вообще не получите taskId) — см. следующий раздел. Изредка какой-то сам по себе допустимый, но неподдерживаемый моделью в комбинации параметр отклоняется только при выполнении задачи, что приводит к data.status: "fail". error.message укажет, какой именно параметр.

Исправление: прочитайте data.error.message, затем сверьтесь со страницей модели, чтобы проверить поддерживаемые ею входные данные (например, страница модели GPT Image 2), удалите или исправьте указанное поле.

Как отличить TASK_FAILED, 4xx и тайм-аут

Три совершенно разные ситуации часто обобщённо называют «сбоем», но способы исправления различаются:

Что вы видите	Значение	Где исправлять
POST возвращает не 2xx (400/401/402/429) и нет taskId	Запрос отклонён, задача вообще не запускалась	Исправить запрос / key / баланс (см. ссылки ниже)
POST возвращает 200 + taskId, опрос показывает data.status: "fail"	TASK_FAILED — задача выполнена и завершилась неудачно	Читать data.error.message (эта статья)
POST возвращает 200 + taskId, опрос дольше вашего дедлайна остаётся в нетерминальном состоянии (например, handling)	Тайм-аут, а не сбой	Продолжать опрос / увеличить тайм-аут / повторить

Если вы вообще не получили taskId, то это не TASK_FAILED, а ошибка запроса:

• HTTP 400 недопустимый, отсутствующий или неподдерживаемый параметр → Исправление ошибки параметров HiAPI 400
• HTTP 401 недействительный API key → Ошибка недействительного API Key
• Недостаточный баланс (отклоняется при создании, поэтому нет задачи, которая могла бы завершиться неудачно) → Исправление ошибки HiAPI 402 недостаточный баланс
• Неизвестный или неопубликованный id модели (MODEL_UNAVAILABLE) → «Модель не существует / недоступна»
• Задача никогда не достигает терминального состояния → Тайм-аут задачи HiAPI и ошибка 504

Сбой аутентификации отклоняется на уровне запроса, возврат — HTTP 401 + {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}}, задача не создаётся, поэтому речи о TASK_FAILED нет.

Чек-лист исправления

1. Опрашивайте задачу, не доверяйте только POST. Отправка лишь сообщает, что задача поставлена в очередь. Вызовите GET /v1/tasks/{taskId} и посмотрите data.status.
2. Убедитесь, что это настоящий сбой: data.status == "fail" (код HTTP по-прежнему 200).
3. Прочитайте data.error.code и data.error.message. message — ваш главный сигнал.
4. Если упоминается входной URL: сделайте URL публично доступным, проверьте через curl -I (200 + прямой content-type медиафайла).
5. Если message обобщённый ("task failed"): считайте это кратковременным сбоем и повторите; если продолжает повторяться, упростите входные данные.
6. Если это детерминированная ошибка вроде CONTENT_POLICY_VIOLATION: это постоянный сбой, не повторяйте автоматически — поможет только изменение входных данных.
7. Убедитесь, что id модели сейчас присутствует в GET /v1/models и полностью совпадает с отправленным. Неизвестный id завершится сбоем при отправке с 400 MODEL_UNAVAILABLE, а не терминальным fail.
8. Совсем нет taskId? Тогда это не TASK_FAILED — перейдите к соответствующему руководству по ошибкам запроса выше.

Минимальный пример проверки

Перед диагностикой конкретной задачи сначала выполните чистый запрос, чтобы убедиться в работоспособности вашего key и соединения. Обратитесь к унифицированному API задач POST https://api.hiapi.ai/v1/tasks, используя id модели как голый id (без суффикса endpoint):

# 1) Отправка — ожидается HTTP 200 + taskId
curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","input":{"prompt":"a red bicycle on a white background","aspect_ratio":"1:1"}}'
# -> {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

# 2) Опрос — подставьте полученный taskId
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-xxxxxxxx \
  -H "Authorization: Bearer sk-YOUR_KEY"
# -> во время выполнения data.status равен "handling", затем становится "success" или "fail"

Если шаг 1 возвращает 200 и taskId, значит ваш key и интерфейс в порядке, и любой сбой — это проблема отдельной задачи, а не интеграции. Если шаг 1 возвращает 401, значит key неверен — управляйте key в консоли HiAPI. Обратите внимание: этот пример выполнит реальную генерацию и может повлечь расходы.

О тарификации: не платите многократно за заведомо провальные задачи

Списывается ли плата за неуспешные задачи, а также как работают предварительное списание и возврат, см. в «Списывается ли плата за неуспешные запросы HiAPI?». Два ключевых момента:

• Не повторяйте слепо автоматически детерминированные сбои. CONTENT_POLICY_VIOLATION, недоступный URL и подобные — каждая повторная попытка это новая задача, и за неё может быть списана плата. Сначала измените входные данные, не позволяйте логике повторов впустую тратить деньги.
• Проверяйте входной URL через curl -I перед отправкой. Одна проверка HEAD бесплатна, а задача, заведомо провальная из-за битой ссылки, может стоить денег.

FAQ

Является ли TASK_FAILED HTTP-статусом? Нет. HTTP-вызов возвращает 200. TASK_FAILED — это значение data.error.code в терминальном ответе, а data.status этого ответа — "fail".

data.status равен "fail", но я ищу "TASK_FAILED" — на что же смотреть? Смотрите каждое в своём месте. Для завершённой задачи data.status всегда "success" или "fail"; "TASK_FAILED" — это обобщённый data.error.code, а неуспешная задача может также содержать более конкретный код (например, INVALID_REQUEST, CONTENT_POLICY_VIOLATION) и полезное для действий message.

Какие TASK_FAILED можно повторять, а какие нельзя? Обобщённый "task failed" (без дополнительных деталей) чаще всего кратковременный, его можно повторить один-два раза; детерминированные сбои с явным кодом (битый URL → INVALID_REQUEST, нарушение контента → CONTENT_POLICY_VIOLATION, отклонённый моделью параметр) повторять бесполезно, нужно менять входные данные.

Моя задача всё время остаётся в handling, не сбоит и не завершается успешно. Это тайм-аут, а не сбой. Продолжайте опрос или увеличьте тайм-аут клиента; см. Тайм-аут задачи HiAPI и ошибка 504.

Я получаю 400 / 401 / 402 вместо taskId. Это отклонение запроса — задача не создавалась, так что никакого «сбоя» нет. Используйте руководства по ссылкам выше, чтобы исправить запрос, key или баланс.

Списывается ли плата за неуспешные задачи? См. «Списывается ли плата за неуспешные запросы HiAPI?», чтобы узнать, как обрабатываются предварительное списание и возврат при сбое.

Как убедиться, что входной URL битый? Прочитайте data.error.message. Проблемы с URL обычно сообщают о невозможности загрузить изображение или видео; проверьте ссылку через curl -I, что она возвращает 200 и является прямым медиафайлом.