Тайм-аут задач HiAPI и ошибка 504: руководство по диагностике и исправлению

В ответе, который возвращает GET /v1/tasks/{id} для задач HiAPI, иногда появляется "status": "fail", "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} — обратите внимание, что сам HTTP-статус этого ответа — 200. Это документированное HiAPI реальное состояние отказа, означающее, что задача начала выполняться, но не успела завершиться в пределах внутреннего временного бюджета. Если вы видите не такой JSON, а клиент просто выбрасывает голый HTTP 504 Gateway Timeout, то это вовсе не ответ API HiAPI: 504 не входит ни в один список документированных статус-кодов HiAPI. В этой статье мы разберём эти два случая отдельно: как читать и исправлять настоящий TASK_TIMEOUT, и откуда вообще берётся 504.

Как на самом деле выглядит ошибка

Процесс выполнения задач HiAPI асинхронный: POST /v1/tasks сразу возвращает taskId, после чего вы опрашиваете GET /v1/tasks/{id}, чтобы получить результат. Поле error появляется только когда status достигает терминального состояния. Настоящий тайм-аут выглядит так:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

Обратите внимание: HTTP-статус этого ответа — 200. Сам запрос опроса успешен, а failed — это задача, подробности отказа находятся в data.error. Это отличается от синхронных ошибок на этапе создания (например, недостаток баланса — это 402, некорректное тело запроса — 400): такие ошибки возвращаются сразу при первоначальном вызове POST /v1/tasks, когда задача ещё даже не создана. TASK_TIMEOUT может произойти только с уже успешно созданной задачей.

А 504 в большинстве случаев вообще не является телом ответа: это статус-код, который самостоятельно выдаёт прокси, балансировщик нагрузки или некоторая клиентская HTTP-библиотека, когда отказывается ждать любого ответа. Документированные HTTP-статусы HiAPI — 200, 400, 402, 404, 409, 415, 422, 503 — среди них нет 504. Если вы видите на самом деле 401, это другая проблема (недействительный или отключённый API Key, а не тайм-аут), и она выходит за рамки этой статьи.

Типичные причины (в порядке вероятности)

1. Настоящий тайм-аут на уровне задачи. Модель получила задачу, но не успела завершить её в пределах внутреннего временного бюджета. Это именно сценарий TASK_TIMEOUT, показанный выше; он чаще встречается на более тяжёлых задачах — большая длительность видео, более высокое разрешение или кратковременная перегрузка самой модели.
2. 504 приходит извне HiAPI. Подавляющее большинство сообщений о «504» — это на самом деле read timeout самого клиента (HTTP-библиотека не дождалась и сдалась), либо корпоративный прокси, VPN или балансировщик нагрузки между вами и api.hiapi.ai оборвал соединение по своим настройкам тайм-аута. Поскольку HiAPI никогда не возвращает 504, это проблема конфигурации на стороне клиента или сети, а не сбой HiAPI.
3. Задача ещё выполняется, но её ошибочно приняли за тайм-аут. queued, handling, archiving — все это нетерминальные состояния; в этот момент поля error просто не существует. Увидев при одном опросе статус, отличный от success, вы не получаете тайм-аут.

Шаги исправления

1. Запросите задачу по taskId и читайте непосредственно status и error.code. Не гадайте причину по одному общему тексту исключения в клиентском коде — вызовите GET /v1/tasks/{id} и посмотрите на само тело ответа.
2. Если status равен "fail", а error.code — "TASK_TIMEOUT": повторите попытку. Документированный способ исправления прост — повторно отправьте задачу новым вызовом POST /v1/tasks (получив новый taskId); менять аккаунт или Key не нужно.
3. Если задача сама по себе тяжёлая, сначала проверьте входные данные. Большая длительность видео, более высокое разрешение или очень объёмный/сложный промпт приближают модель к верхней границе её временного бюджета. Если одна и та же конфигурация раз за разом уходит в тайм-аут, попробуйте меньшее разрешение/длительность или другую модель.
4. Если вы видите на самом деле голый 504 (без тела JSON с error.code), проблема вне HiAPI. Проверьте read timeout, настроенный в вашем HTTP-клиенте или SDK — многие значения по умолчанию слишком малы (10–30 секунд), а в асинхронном процессе не стоит блокировать один длинный запрос, лучше опрашивать отдельно. Также убедитесь, не идёт ли трафик через корпоративный прокси, VPN-шлюз или балансировщик нагрузки, которые могут обрывать соединение по своим настройкам тайм-аута совершенно независимо от HiAPI.
5. Если status по-прежнему queued, handling или archiving, пока не повторяйте попытку. Ничего на самом деле не провалилось. Более полную диагностику см. в руководстве по диагностике зависаний/тайм-аутов задач hiapi (на английском).

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

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "a single red apple on a white background, studio lighting"
    }
  }'

Он сразу вернёт taskId:

{ "code": 200, "data": { "taskId": "tk-hiapi-xxxxxxxx" }, "message": "success" }

Затем опрашивайте его:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-xxxxxxxx \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Нормальная задача в итоге вернёт "status": "success" и результат. Задача, действительно ушедшая в тайм-аут, вернёт показанную выше структуру TASK_TIMEOUT. Если же вы получили 504 на уровне соединения и вообще без тела JSON-ответа, это значит, что ответ так и не смог вернуться от API HiAPI — проверьте по шагам выше настройки тайм-аута своего клиента и сетевой путь, а не подозревайте проблемы с аккаунтом.

Связанные внутренние ссылки

• Консоль HiAPI
• Создание асинхронной задачи (документация API)
• руководство по диагностике зависаний/тайм-аутов задач hiapi (на английском)

FAQ

TASK_TIMEOUT в HiAPI и HTTP 504 Gateway Timeout — это одно и то же? Нет. TASK_TIMEOUT — документированный HiAPI код ошибки, который появляется в обычном ответе 200 и означает, что собственный status задачи стал fail, то есть задача превысила время выполнения внутри. 504 — общий HTTP-статус, который выдают некоторые прокси, балансировщики нагрузки и клиентские HTTP-библиотеки, когда отказываются ждать ответа; API HiAPI вообще не документирует и не возвращает 504, поэтому буквальный 504, который вы видите, обязательно связан с каким-то звеном между вами и HiAPI или с вашим собственным клиентом, отказавшимся ждать, а не со сбоем серверов HiAPI.

Что делать при TASK_TIMEOUT? Просто отправьте новую задачу. Документированный способ исправления TASK_TIMEOUT — повторная попытка; отдельного шага разблокировки нет, и если один и тот же ввод не уходит в тайм-аут раз за разом, менять промпт или параметры не нужно.

Будет ли списание дважды при повторной попытке после тайм-аута? В документированной таблице кодов ошибок HiAPI это явно не указано. Если для вас это важно, проверьте записи об использовании в консоли именно по этому taskId, а не делайте выводы на основе предположений.

Мой HTTP-клиент выбросил исключение тайм-аута, а не JSON в формате TASK_TIMEOUT — это одно и то же? Нет. Тайм-аут самого клиента (например, ReadTimeout HTTP-библиотеки или 504, возвращённый корпоративным прокси) означает, что ваше соединение сдалось раньше, чем получило какой-либо ответ HiAPI, и это не значит, что задача сама провалилась. Поскольку /v1/tasks асинхронный, обычное решение — увеличить read timeout клиента (или вообще не блокироваться на изначальном POST в ожидании) и отдельно опрашивать GET /v1/tasks/{id}, пока не увидите терминальное состояние.

Задача уже несколько минут в queued или handling, ошибки нет — это считается тайм-аутом? Пока нет. queued, handling, archiving — нетерминальные состояния, и поле error появится только когда status станет fail. Если задача действительно никак не завершается, смотрите полный разбор причин незавершённости, включая накопление очереди, в руководстве по диагностике зависаний/тайм-аутов задач hiapi (на английском).