Ошибки вышестоящего сервиса HiAPI 502 / 503: причины и способы устранения

Вы вызываете POST https://api.hiapi.ai/v1/tasks (или опрашиваете GET /v1/tasks/{id}), и в ответ приходит не обычный 200 с taskId, а 502 Bad Gateway или 503 Service Unavailable. Оба являются ответами 5xx, а значит, проблема на стороне сервера или транспорта, а не в вашем запросе: вы не отправляли неверные параметры, неверный ключ или некорректно сформированное тело запроса. 503 — это задокументированный в документации HiAPI сигнал «платформа временно недоступна», указывающий, что следует повторить попытку; 502 же — это ответ уровня шлюза, возникший где-то на пути. Это руководство объясняет, как убедиться в этом, как безопасно повторять попытки, не дублируя работу, и как отличать 502/503 от тайм-аута 504 и результата TASK_FAILED.

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

В строке состояния HTTP вы увидите одно из следующего вместо обычного 200:

• 503 Service Unavailable — этот код задокументирован. Документация асинхронного API HiAPI указывает 503 как «платформа временно недоступна; повторите попытку позже с экспоненциальной задержкой», соответствующий бизнес-код — TEMPORARILY_UNAVAILABLE («Сервис генерации временно недоступен. Повторите попытку позже; если проблема сохраняется, обратитесь в поддержку.»). Синхронные ошибки HiAPI используют плоский JSON-конверт — в документации для случая 400 указано {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"} — поэтому 503, возвращаемый API, также должен использовать тот же конверт с error_code: "TEMPORARILY_UNAVAILABLE".
• 502 Bad Gateway — этот код отсутствует в задокументированных кодах состояния HiAPI. В стандартном HTTP 502 означает, что шлюз или прокси получил недопустимый или пустой ответ от следующего узла, к которому он обратился. Поэтому полученный вами 502 сгенерирован шлюзом на пути — возможно, уровнем edge/CDN, балансировщиком нагрузки или прокси в вашей собственной сети — а не приложением HiAPI, возвращающим свой обычный JSON-конверт. Тело ответа обычно представляет собой короткую HTML- или простую текстовую страницу шлюза, и само это не-JSON тело служит сигналом: это транспортная/шлюзовая ситуация, а не ошибка приложения с фиксированной, задокументированной нагрузкой.

В любом случае состояние — 5xx: проблема на стороне сервера или транспорта, а не в вашем запросе. Это противоположность 4xx — 400 (неверный параметр), 401 (неверный ключ; HiAPI возвращает вложенный {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}) или 402 (недостаточно средств) — эти требуют изменения чего-то на вашей стороне для исправления. 502/503 невозможно исправить, изменив тело запроса.

Частые причины (в порядке убывания вероятности)

1. Кратковременная перегрузка платформы или окно обслуживания → 503 TEMPORARILY_UNAVAILABLE. Это ожидаемая, задокументированная ситуация. Она проходит сама собой, и повторная попытка с задержкой увенчается успехом.
2. Мгновенный сбой шлюза или прокси на пути → 502. Уровень edge/CDN, балансировщик нагрузки или прокси в вашей собственной сети кратковременно не смог переслать ответ. Это также временно.
3. Всплеск трафика вызвал ограничение. При высокой нагрузке вы можете вместо этого увидеть 429 RATE_LIMITED («Повторите попытку позже; избегайте немедленной повторной отправки того же запроса»). Если состояние 429, решение — снизить скорость отправки, а не повторять попытки с большей интенсивностью.
4. Бэкенд запрошенной модели временно недоступен. HiAPI фиксирует это на уровне задачи как MODEL_UNAVAILABLE («Повторите попытку позже или переключите модель»); кратковременный сбой уровня платформы, обслуживающей эту модель, также может проявляться как 503.
5. Это не ошибка ключа, некорректное тело запроса или недостаток средств. Это 401 / 400 / 402 соответственно, и ни один из них не проявляется как 502 или 503.

Способы исправления по порядку

1. Убедитесь, что это 5xx, а не 4xx. Сначала посмотрите на код состояния. 502/503 относятся к стороне сервера/транспорта; 400, 401, 402, 404, 409, 415, 422 и 429 относятся к вашей стороне. Если это действительно 502/503, не начинайте переписывать тело запроса — это поможет только при 4xx.
2. Повторяйте попытки с экспоненциальной задержкой и джиттером. Документация явно требует экспоненциальной задержки для 503. Безопасный клиентский шаблон — начать примерно с 1 секунды, удваивать при каждой попытке (2 с, 4 с, 8 с…), с верхним пределом около 30–60 секунд и добавлением случайного джиттера, чтобы множество клиентов не повторяли попытки синхронно. Эти интервалы — рекомендуемый клиентский шаблон, а не гарантия времени, опубликованная HiAPI.
3. Сделайте отправку идемпотентной. Установите заголовок Idempotency-Key в POST /v1/tasks (любая строка UTF-8, до 255 байт). Если из-за 502/503 вы не уверены, была ли задача фактически создана, повторная попытка с тем же ключом безопасна: тот же ключ + то же тело запроса вернут исходный taskId с заголовком ответа Idempotent-Replay: true, без создания второй задачи и без второго списания. Ключи ограничены областью действия аккаунта и истекают через 24 часа. Полное соглашение см. в документации Unified Async API.
4. Не выполняйте слепой повторный POST без ключа. Если вы отправили запрос без Idempotency-Key и получили 502/503, возможно, вы уже создали задачу, которую не видите — у вас нет taskId для опроса, поэтому наивное повторение грозит дублированием работы и повторным списанием. Добавьте ключ до любых повторных попыток в любом масштабе.
5. Если 502/503 возникает во время опроса, просто продолжайте опрос. 5xx, возвращаемый GET /v1/tasks/{id}, не меняет состояние задачи. Терминальные состояния (success / fail) фиксируются по достижении и никогда не переходят друг в друга, поэтому достаточно повторить опрос после задержки. Либо зарегистрируйте callback.url, чтобы получать уведомление о терминальном состоянии без опроса через временные 5xx — доставка выполняется как минимум один раз, поэтому дедуплицируйте по taskId.
6. Отличайте это от сбоя на уровне задачи. Если вы вместо этого получили HTTP 200 с "status": "fail", это не 502/503 — задача была принята, выполнена и завершилась неудачей. Обрабатывайте TASK_FAILED («Повторите попытку один раз; если проблема сохраняется, обратитесь в поддержку») или TASK_TIMEOUT («Повторите задачу») соответствующим образом, а не выполняйте слепые повторные попытки шлюза.
7. Если проблема сохраняется, эскалируйте, а не долбите. Если 502/503 продолжает появляться после нескольких повторных попыток с задержкой в течение нескольких минут, рассматривайте это как временное событие платформы, а не как проблему, решаемую грубой силой. Прекратите агрессивные повторные попытки и обратитесь в поддержку, указав request_id из тела ошибки, если он там есть. Вы можете проверить состояние своего аккаунта и связность через консоль HiAPI.

Сравнение 502 / 503 с 504 и TASK_FAILED

Их легко спутать, поскольку все они означают «не вернулось чисто», но требуют разной обработки:

Ответ	Код состояния HTTP	Источник	Списаны ли средства за задачу?	Что делать
503 Service Unavailable	503 (задокументирован)	Платформа HiAPI — временно недоступна или перегружена	Невозможно определить из ответа; задача могла быть создана	Повторите попытку с задержкой и тем же Idempotency-Key
502 Bad Gateway	502 (отсутствует в документации HiAPI)	Шлюз/прокси на пути (edge, балансировщик нагрузки или ваш собственный прокси)	Невозможно определить из ответа	Идемпотентный повтор с задержкой; если возникает только из вашей сети, подозревайте прокси на вашей стороне
504 Gateway Timeout	504 (отсутствует в документации HiAPI)	Шлюз или прокси на пути, прекративший ожидание (504 не указан в документации HiAPI)	Невозможно определить из ответа	То же, что для 502; HiAPI сообщает о своих тайм-аутах как TASK_TIMEOUT
TASK_TIMEOUT	200 + "status": "fail"	HiAPI — задача выполнялась, но превысила временной бюджет	Нет (зарезервированная сумма возвращена)	Повторите задачу как новый запрос
TASK_FAILED	200 + "status": "fail"	HiAPI — задача была принята и выполнена, затем завершилась неудачей	Нет (зарезервированная сумма возвращена)	Повторите один раз, затем прочитайте error.message
429 RATE_LIMITED	429	HiAPI — вы отправляете слишком быстро	Задачи нет	Задержка; не отправляйте повторно немедленно
400 / 401 / 402	4xx	HiAPI — сторона клиента (ошибка тела запроса/ключа/баланса)	Нет	Исправьте запрос, ключ или баланс; повтор не поможет

Правило в одну строку: 502/503/504 — это транспортные ошибки HTTP, не несущие никакого результата задачи; а TASK_FAILED / TASK_TIMEOUT приходят в виде HTTP 200 с "status": "fail" и объектом error. Первые означают «вы не знаете, доставлен ли запрос»; вторые — «запрос доставлен, задача выполнена и завершилась неудачей».

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

Докажите, что ваш ключ и связность в порядке, с помощью одной чистой отправки и изолируйте 502/503 как временную проблему. Используйте id модели, в которой вы уверены (например, gpt-image-2/text-to-image), и включите Idempotency-Key, чтобы повторные попытки были безопасны:

# A healthy submit returns 200 with a taskId. If this works but a specific
# call just 502/503'd, that 502/503 was transient — not your setup.
curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red bicycle on a white background"}}'

# Then poll the task you just created (swap in the returned id):
curl -sS https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Если сама отправка возвращает 200 и taskId, значит ваша аутентификация и сетевой путь в порядке, а предыдущий 502/503 был временной ситуацией на стороне сервера/транспорта — повторите неудачный вызов (повторное использование того же Idempotency-Key вернёт исходную задачу, а не дубликат). Если отправка вместо этого возвращает 401 или 400, это проблема на стороне клиента, а не 502/503.

Связанные материалы

• Тайм-аут задачи HiAPI и ошибка 504: как исправить — почему исходный 504 исходит не от HiAPI и что означает TASK_TIMEOUT.
• Ошибка HiAPI TASK_FAILED: причины и способы устранения — обработка задач, возвращающих 200 + "status": "fail".
• Когда задания hiapi /v1/tasks зависают или истекают по времени: диагностика и повторные попытки — подробнее об интервалах опроса и стратегиях повтора.
• Как исправить ошибку ограничения скорости (429) HiAPI — когда реальная проблема — скорость отправки, а не доступность.
• Почему за неудачные запросы HiAPI всё равно списываются средства? — как работают резервирование и возврат средств для неудачных задач.

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

502 или 503 — это моя вина? Нет. Оба являются ответами 5xx, относящимися к стороне сервера или транспорта. Ваш API-ключ и тело запроса не являются причиной — 4xx (400/401/402) — это та категория, которую вызвали вы и можете исправить. Правильный ответ на 502/503 — идемпотентный повтор, а не изменение кода.

В чём разница между 502 и 503 в HiAPI? 503 — это задокументированный в HiAPI код «платформа временно недоступна» (error_code: TEMPORARILY_UNAVAILABLE), исходящий от самой платформы. 502 отсутствует в задокументированных кодах состояния HiAPI; в стандартном HTTP он выдаётся шлюзом или прокси на пути, когда вышестоящий сервис возвращает недопустимый ответ. Оба временны и требуют повтора с задержкой, но 502 также может указывать на прокси в вашей собственной сети.

Чем 503 отличается от 504? 503 означает, что сервис в настоящее время временно недоступен или перегружен. 504 Gateway Timeout означает, что где-то ожидание ответа заняло слишком много времени. В документации HiAPI 504 не указан; если вы его видите, значит шлюз или прокси где-то на пути прекратил ожидание. Собственный статус HiAPI «заняло слишком много времени» — это результат задачи TASK_TIMEOUT (HTTP 200 + "status": "fail"). См. руководство по 504 выше.

Как отличить 502/503 от результата TASK_FAILED? Смотрите на код состояния HTTP. 502/503 — это HTTP-ошибка без нагрузки задачи. TASK_FAILED возвращается как HTTP 200 с "status": "fail" и объектом error — задача была принята и выполнена. Для 502/503 используйте повтор с задержкой; для TASK_FAILED повторите один раз, затем прочитайте error.message.

Спишут ли с меня дважды или создадут ли дубликат задачи при повторе после 502/503? Нет, если вы отправляете заголовок Idempotency-Key в POST /v1/tasks. Повторное использование того же ключа + тела запроса вернёт исходный taskId (Idempotent-Replay: true), не создавая дубликат задачи. Кроме того, за неудачные задачи никогда не списываются средства — как только задача достигает терминального состояния неудачи, сумма, зарезервированная при создании, возвращается полностью.

Как долго следует выдерживать задержку и когда эскалировать? Используйте экспоненциальную задержку с джиттером (например, 1 с, 2 с, 4 с, 8 с, с верхним пределом и добавлением случайности). Если 502/503 продолжает возвращаться после нескольких повторных попыток в течение нескольких минут, прекратите агрессивные повторы и обратитесь в поддержку, указав request_id из тела ошибки — устойчивый 5xx обычно означает временное событие платформы, а не проблему, которую решит более быстрый цикл повторов.

Стоит ли изменять тело запроса при получении 502/503? Нет. 502/503 — это не ошибка валидации, поэтому изменение параметров не поможет и может замаскировать истинную временную причину. Оставьте запрос без изменений, добавьте Idempotency-Key, если он ещё не добавлен, и повторите попытку с задержкой.