Исправление ошибок ограничения скорости HiAPI (429): причины и способы устранения

Когда шлюз HiAPI возвращает HTTP 429 Too Many Requests, это означает, что используемый вами API-ключ за короткое время превысил допустимую частоту запросов или лимит параллельных запросов к https://api.hiapi.ai/v1/tasks (или к эндпоинту опроса GET /v1/tasks/{taskId}). Тело ответа следует единому формату ошибок HiAPI — {"error":{"type":"hiapi_error","code":"...","request_id":"..."}} — и сопровождается статус-кодом 429. Для решения этой проблемы почти никогда не нужно писать в поддержку — достаточно добавить на клиенте небольшую логику «повтор + ограничение скорости». В этой статье рассказывается, что это за ошибка, почему она возникает и какие конкретные шаги помогут от неё избавиться.

Как выглядит HiAPI 429

Типичный запрос на сетевом уровне выглядит примерно так:

> POST /v1/tasks HTTP/1.1
> Host: api.hiapi.ai
> Authorization: Bearer hi-sk-...
> Content-Type: application/json

< HTTP/1.1 429 Too Many Requests
< Content-Type: application/json
<
{"error":{"type":"hiapi_error","code":"rate_limit_exceeded","request_id":"req_..."}}

Два важных момента:

• Статус-код — 429, а не 401/403. 401 означает, что ключ неверный или отсутствует; 429 означает, что с ключом всё в порядке, просто вы отправляете запросы слишком быстро. Не путайте эти два случая.
• Тело ответа — это JSON в формате ошибки hiapi_error. Некоторые HTTP-клиенты по умолчанию показывают только статус-код; если ваш код выполняет повторные попытки без логирования, вы потеряете такие подсказки для диагностики, как request_id.

Если вы вызываете такие модели, как GPT Image 2, Nano-Banana, flux, Seedance, Wan или HappyHorse, все они работают на одном и том же эндпоинте асинхронных задач и поэтому используют общий лимит скорости в разрезе ключа.

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

По нашему опыту, от наиболее к наименее вероятной:

1. Всплеск параллельных запросов с одного ключа (burst fan-out). Вы перебираете пакет промптов и параллельно вызываете POST /v1/tasks для каждого, не ограничивая параллелизм. Даже десятка параллельных созданий задач на новом аккаунте достаточно, чтобы достичь лимита.
2. Агрессивный опрос GET /v1/tasks/{taskId}. Плотный цикл while True: poll(); sleep(0.2) считается таким же объёмом запросов, как и создание задач. Опрос с субсекундным интервалом — главная причина ситуации «я создал всего одну задачу, а всё равно получаю 429».
3. Лимит параллельных задач на уровне аккаунта. Более тяжёлые модели — видео (seedance-2.0, wan2.7-video/*, happyhorse-1.0) и варианты изображений @pro — учитываются по более строгому лимиту параллельных задач. Массовая отправка таких задач за один раз приведёт к 429, даже если частота запросов в минуту невысока.
4. Один ключ используется в нескольких окружениях. dev, staging и prod используют один и тот же HIAPI_API_KEY, и нагрузка суммируется. По отдельности каждое окружение в норме, но вместе они выводят ключ за лимит.
5. Исчерпана квота тарифа. Бесплатная квота или почти исчерпанный платный тариф иногда проявляются как 429, а не как ошибка биллинга, особенно во время акций.

О конкретных порогах: количество запросов в минуту и лимиты параллелизма HiAPI определяются вашим тарифным уровнем, и платформа не публикует фиксированные цифры. Поэтому приведённые ниже значения параллелизма (5, 3, 2) — это эмпирические отправные точки, а не официальные лимиты — сверяйтесь с реальным использованием в панели управления.

Шаги по исправлению

Выполняйте по порядку. Большинство команд после шага 3 перестают получать оповещения.

1. Добавьте экспоненциальную задержку с джиттером

Любой клиент, взаимодействующий с api.hiapi.ai, при получении 429 должен повторять запрос с увеличивающейся задержкой — никогда не повторяйте сразу. Безопасная реализация по умолчанию:

import random, time, requests

def post_task_with_backoff(body, key, *, max_retries=5):
    delay = 1.0
    for attempt in range(max_retries):
        r = requests.post(
            "https://api.hiapi.ai/v1/tasks",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=body, timeout=30,
        )
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        retry_after = r.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else delay + random.random()
        time.sleep(min(wait, 30.0))
        delay = min(delay * 2, 30.0)
    raise RuntimeError("rate-limited after retries")

Этот код делает две вещи правильно: ограничивает задержку 30 секундами и отдаёт приоритет заголовку Retry-After, если он присутствует. Даже если в вашем ответе 429 нет Retry-After, стратегии «ограничение + джиттер» достаточно, чтобы справиться с большинством всплесков.

2. Ограничьте параллелизм клиента по ключу

Добавление семафора на клиенте — самое эффективное изменение из всех. Если не знаете, какое значение выбрать, начните с 5:

import asyncio, httpx

sem = asyncio.Semaphore(5)

async def create_task(client, body):
    async with sem:
        r = await client.post("https://api.hiapi.ai/v1/tasks", json=body, timeout=30)
        return r.json()

5 одновременно выполняющихся задач — комфортная нагрузка для большинства аккаунтов. Если 429 всё ещё возникает, снизьте до 3. Для тяжёлых видеомоделей обычно нужен отдельный, более низкий семафор (попробуйте 2).

3. Перейдите с опроса на callback.url

Для производственных нагрузок опрос GET /v1/tasks/{taskId} — не лучший вариант по умолчанию. Передайте callback.url в теле запроса, и HiAPI отправит результат POST-запросом, когда задача достигнет конечного состояния:

{
  "model": "Nano-Banana",
  "input": { "prompt": "a calm lake at dawn", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

Это сжимает модель запросов O(количество задач × количество опросов) до O(количество задач) — обычно это снижение объёма вызовов в 10–50 раз, и это почти мгновенное лекарство от 429, вызванных опросом. Оставьте GET /v1/tasks/{taskId} для локальной отладки и редких разовых вызовов.

4. Замедлите опрос и добавьте джиттер

Если вы не можете использовать колбэки (офлайн-скрипты, локальные notebook, резервная сверка), не опрашивайте чаще, чем раз в 2–5 секунд, и добавляйте джиттер, чтобы несколько воркеров не шли в ногу:

import random, time
time.sleep(2 + random.random() * 3)  # 2–5 секунд, с джиттером

5. Разделите ключи по окружениям

На странице API-ключей HiAPI создайте отдельный ключ для каждого окружения — dev, staging, prod. Всплески в каждом окружении изолированы друг от друга, а при утечке ключа его можно отозвать отдельно, не затрагивая другие окружения.

6. Проверьте текущее использование

Откройте панель управления HiAPI и убедитесь, достигли ли вы лимита параллелизма/тарифа или это был просто кратковременный всплеск; квоты тарифных уровней можно сверить на странице цен. Если использование намного ниже тарифа, а 429 всё равно возникает, причина почти наверняка во всплеске на стороне клиента, а не в аккаунте.

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

После того как слой повторных попыток готов, самый дешёвый способ убедиться, что вся цепочка работает, — одна задача Nano-Banana. Замените $HIAPI_API_KEY на свой ключ:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana",
    "input": { "prompt": "a single red apple on a white table", "aspect_ratio": "1:1" }
  }'

Успешный ответ выглядит примерно так: {"code":200,"data":{"taskId":"tk-hiapi-..."}}. Затем опросите один раз:

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

Статус пройдёт через queued → handling → archiving → success, а итоговый data.output[0].url — это ваша картинка. Если этот один цикл возвращает 200, но пакетные задачи по-прежнему получают 429, проблема в параллелизме на клиенте, а не в вашем ключе.

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

Почему я получаю 429, хотя отправил всего один запрос?

Почти всегда реальный объём запросов создаёт цикл опроса, а не создание задачи. Опрос 5 параллельных задач с интервалом 200 мс — это уже 25 запросов в секунду. Замедлите опрос до 2–5 секунд или перейдите на callback.url.

Всегда ли HiAPI возвращает заголовок Retry-After?

Относитесь к Retry-After как к рекомендованному значению: если он есть — используйте его, если нет — откатитесь к экспоненциальной задержке (1s, 2s, 4s… с ограничением 30s). В любом случае не повторяйте запрос без задержки — это только усилит всплеск.

429 и 401 / 403 — это одно и то же?

Нет. 401 / 403 означают ошибку аутентификации и используют тот же формат ошибки hiapi_error, например {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"req_..."}} (по нашим наблюдениям, message при 401 сообщает "This API key is invalid. Check that it is correct..."). Если вы видите 401/403, проверьте значение ключа на странице API-ключей — задержка здесь не поможет.

Можно ли просто повысить лимит скорости?

Если вашему трафику действительно нужен более высокий лимит параллелизма, сначала уточните квоту тарифа на странице цен, а затем свяжитесь с поддержкой оттуда. На практике описанные выше исправления решают более 90% проблем с 429 без изменения каких-либо лимитов.

В чём разница между 429 на /v1/tasks и 429 на /v1/tasks/{taskId}?

Эндпоинт лишь говорит о том, что вы делали в тот момент — оба используют общий бюджет скорости в разрезе ключа. 429 на эндпоинте создания указывает на всплеск (ограничьте параллелизм, перейдите на пакетную обработку); 429 на эндпоинте опроса указывает на плотный цикл опроса (замедлите темп или переключитесь на колбэки). Полная структура запросов/ответов описана в HiAPI Quickstart и документации по аутентификации.

Итог

429 — это нормальный, восстановимый сигнал, который выдаёт любой производственный API-шлюз. Добавьте экспоненциальную задержку, ограничьте параллелизм клиента, замените опрос на колбэки и проверьте использование в панели управления. Выполнив эти четыре вещи, вы сможете полностью забыть о 429. Эта страница — упрощённая китайская версия английского оригинала «How to Fix HiAPI Rate Limit (429) Errors»; технические детали соответствуют оригиналу.