Ошибка 429 и лимиты: как генерировать без отказов

01Что значит ответ 429?

Ответ 429 приходит, когда запросов слишком много: API отказывает, пока лимит не освободится. Частота запросов и число заданий считаются на аккаунт, а не на ключ: все ключи делят один счёт, и дополнительный ключ его не увеличивает. По умолчанию значения одинаковы для любого аккаунта, и для только что зарегистрированного тоже.

У вашего аккаунта лимит может быть другим. Если его не хватает, напишите в поддержку: назовите аккаунт и нужный объём.

В лимит частоты входят запуск генераций, загрузка файлов, чтение каталога моделей и чтение баланса. Опрос задания считается отдельно, по своему правилу. Место в лимите заданий занято, пока задание стоит в очереди или рисуется.

Ещё два случая не связаны с частотой запросов. Аккаунт, который зарегистрировался сам и ещё не пополнял баланс, может использовать не больше 100 образцов в сутки; после первого пополнения лимита нет. А если с одного IP-адреса приходит 30 отказов 401 или 30 отказов 403 в минуту, адрес блокируется до 120 секунд: ответ 429 содержит details.reason = burst_block.

Как отличить один 429 от другого

Статус один, причин несколько. Смотрите на error.code и error.details: по ним выбирают, что делать. Текст error.message написан для человека и может меняться, не разбирайте его программой.

HTTP/1.1 429 Too Many Requests
Retry-After: 17

{
  "error": {
    "code": "ERR_RATE_LIMIT",
    "message": "rate limit exceeded",
    "details": { "limit": 120, "window": "1m", "retry_after": 17 }
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 2

{
  "error": {
    "code": "ERR_QUOTA_EXCEEDED",
    "message": "concurrency limit reached",
    "details": { "limit": 100, "scope": "account" }
  }
}

В первом ответе details.limit и details.window называют сработавший лимит, а details.retry_after — паузу в секундах. Во втором details.scope = "account" значит, что все места заняты заданиями аккаунта: дождитесь готовых и отправляйте новые реже. У слишком раннего опроса в details лежит min_interval_seconds.

02Сколько запросов отправлять одновременно?

Предел задан двумя числами: на весь аккаунт не больше 100 заданий в очереди или в работе и не больше 120 запросов в минуту. Сколько из этого занимать, решаете вы, а правило простое: держите очередь у себя и запускайте новое задание, когда освободилось место, а не пачкой.

1. Считайте на весь аккаунт. Если на нём работают несколько сервисов, лимит у них общий: назначьте каждому долю и оставьте запас на повторы.
2. Освобождайте место по событию. Задание стало completed или failed — запускайте следующее. Узнать об этом можно вебхуком, о нём ниже.
3. Учитывайте все запросы. В 120 запросов в минуту входят не только запуски: загрузка файлов, чтение каталога моделей и баланса тоже считаются.
4. Распределяйте запуски по минуте. 120 запросов в минуту — в среднем два в секунду; серия запросов подряд быстро расходует окно.

03Как повторять запрос после 429?

Правило такое: ждите не меньше Retry-After секунд (заголовок приходит в ответах 429 и 503), добавьте небольшую случайную задержку, чтобы процессы не повторяли запрос одновременно, и ограничьте число попыток. Сохраните тело запроса, ключ API и ключ повтора X-Idempotency-Key: повтор той же отправки тогда не создаст второе задание и второе списание.

• Новая картинка — новый ключ повтора. Повтор той же отправки берёт прежний ключ.
• idempotency_in_flight. Первая отправка с этим ключом ещё обрабатывается: подождите Retry-After и повторите с тем же ключом.
• Опрос задания. Ждите не меньше большего из details.min_interval_seconds и Retry-After: заголовок иногда указывает меньший интервал.
• burst_block. Остановите повторы, устраните причину отказов доступа (неверный ключ, отключённый аккаунт) и продолжайте только после Retry-After.

Пример ниже повторяет отправку по этим правилам.

# Нужны bash, curl и uuidgen. Ключ повтора создаётся один раз на операцию.
IDEMPOTENCY_KEY="$(uuidgen)" || exit 1
curl -i --max-time 30 \
  -X POST https://api.rendergrid.io/api/public/v1/images/generate \
  -H "Authorization: Bearer $RENDERGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "nano-banana-2.1",
    "prompt": "Пять деревянных кубиков в ровный ряд на светло-сером фоне",
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }'

# при ответе 429 прочитайте заголовок Retry-After, подождите
# и повторите этот же запрос с тем же $IDEMPOTENCY_KEY

import os
import random
import time
import uuid

import requests

API = "https://api.rendergrid.io/api/public/v1"


def submit_with_backoff(payload, idempotency_key, max_attempts=5):
    key = os.environ["RENDERGRID_API_KEY"]
    headers = {
        "Authorization": f"Bearer {key}",
        # один и тот же на все попытки
        "X-Idempotency-Key": idempotency_key,
    }
    for attempt in range(max_attempts):
        response = requests.post(
            f"{API}/images/generate",
            headers=headers, json=payload, timeout=(10, 120),
        )
        if response.status_code != 429:
            return response
        try:
            body = response.json()
        except ValueError:
            body = {}
        details = body.get("error", {}).get("details", {})
        last = attempt + 1 == max_attempts
        if details.get("reason") == "burst_block" or last:
            # блокировку и последнюю попытку отдаём наверх
            return response
        wait = int(response.headers.get("Retry-After", "2"))
        # ждём не меньше Retry-After
        time.sleep(max(0, wait) + random.uniform(0, 1))


payload = {
    "model": "nano-banana-2.1",
    "prompt": "Пять деревянных кубиков в ровный ряд на светло-сером фоне",
    "resolution": "1K",
    "aspect_ratio": "1:1",
}
response = submit_with_backoff(payload, str(uuid.uuid4()))
print(response.status_code, response.text)

// Node.js 22+, файл .mjs
import { randomUUID } from "node:crypto";

const API = "https://api.rendergrid.io/api/public/v1";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function submitWithBackoff(payload, idempotencyKey, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(`${API}/images/generate`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}`,
        "Content-Type": "application/json",
        // один и тот же на все попытки
        "X-Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(payload),
      signal: AbortSignal.timeout(120_000),
    });
    if (response.status !== 429) return response;
    const body = await response.clone().json().catch(() => ({}));
    const last = attempt + 1 === maxAttempts;
    if (body.error?.details?.reason === "burst_block" || last) {
      // блокировку и последнюю попытку отдаём наверх
      return response;
    }
    const wait = Number(response.headers.get("Retry-After") ?? 2);
    const delay = Math.max(0, wait);
    // ждём не меньше Retry-After
    await sleep((delay + Math.random()) * 1000);
  }
}

const response = await submitWithBackoff(
  {
    model: "nano-banana-2.1",
    prompt: "Пять деревянных кубиков в ровный ряд на светло-сером фоне",
    resolution: "1K",
    aspect_ratio: "1:1",
  },
  randomUUID(),
);
console.log(response.status, await response.text());

Пример повторяет только 429, остальные ответы отдаёт вашему коду, а при burst_block останавливается. Пять попыток — настройка примера, а не рекомендация: в других примерах документации их три.

04Как опрашивать задание, чтобы не получить 429?

Одно задание одним ключом спрашивайте не чаще раза в 5 секунд и только до статуса completed или failed: на конечном статусе опрос прекращают. Слишком ранний опрос получит 429 ERR_RATE_LIMIT.

Ещё два правила из документации. Ограничьте общее время ожидания: если оно вышло, сохраните id и продолжите позже, тайм-аут вашего клиента задание не отменяет. Если опрашивают несколько процессов, согласуйте между ними общий интервал. Чтобы не опрашивать вовсе, подключите вебхук.

05Как заменить частый опрос вебхуком?

Передайте webhook_url в каждом запросе генерации, для которого нужно уведомление. Когда задание станет completed или failed, мы пришлём на этот адрес подписанный POST с событием creation.completed или creation.failed. Адрес должен быть публичным HTTPS.

Что учесть в обработчике:

• Проверьте подпись. Это HMAC-SHA256 от строки из X-Timestamp, точки и исходного тела; она лежит в заголовке X-Webhook-Signature-256 как sha256= и 64 шестнадцатеричных знака. Считайте её по исходным байтам, до разбора JSON. Окно свежести метки времени в примерах — 300 секунд: это правило получателя.
• Отвечайте быстро. Любой ответ 2xx значит «получили»; мы ждём ответа 10 секунд. Сначала сохраните событие или поставьте его в очередь, скачивание картинок оставьте на потом.
• Готовьтесь к повторам. Если ответа нет или он не 2xx, мы повторяем доставку: по умолчанию до пяти попыток, через 60, 120, 240 и 480 секунд после предыдущей. Выполняйте действие один раз на пару (id, event).
• Держите опрос про запас. Доставка не гарантируется: если вебхук не пришёл, спросите задание методом GET /creations/{id}.

Вебхук убирает опрос, но остальные лимиты остаются: запуски и число заданий в работе считаются как прежде. Про очередь на своей стороне, вебхуки и ключ идемпотентности подробнее — в статье «Генерация пачками: очередь, вебхуки и ключ идемпотентности» и в разделе «Вебхуки» документации.

06Что приходит, когда задание готово?

Когда задание дошло до completed, в result_urls лежат ссылки на готовые файлы. Файлы хранятся сутки, поэтому скачивайте их сразу: опрос срок хранения не продлевает.

Ниже три обычных результата Nano Banana 2.1 в 1K: по одной попытке на каждый, с промптами. Это успешные результаты, а не снимки ошибки. Ошибку 429 они не показывают, а время и нагрузку при их создании мы не измеряли.

Промпт: пять кубиков в ровный ряд

Пять одинаковых деревянных кубиков стоят в прямой горизонтальной линии на светло-сером фоне. Расстояния между кубиками одинаковые, передние грани выровнены. Камера чуть выше уровня предметов, мягкий свет слева. Все кубики целиком, ровные тени и широкие поля. Без надписей, логотипов, людей и водяных знаков.

1K · 1:1 · одна попыткаКопировать промпт

Промпт: девять чашек сеткой три на три

Девять маленьких белых керамических чашек без ручек расположены сеткой три на три. Вид строго сверху, интервалы ровные, отверстия чашек одинакового размера. Матовый бежевый фон, мягкое равномерное освещение, тонкие тени под чашками и свободная рамка вокруг всей группы. Без надписей, логотипов, людей и водяных знаков.

1K · 1:1 · одна попыткаКопировать промпт

Промпт: пять баночек дугой

Пять одинаковых закрытых баночек кремового цвета образуют плавную дугу на песочном фоне. Вид немного сверху, расстояния между банками равные. Мягкий свет справа, гладкие круглые крышки и отдельные тени. Не обрезайте ни одну банку, оставьте открытый центр дуги. Без надписей, логотипов, людей и водяных знаков.

1K · 1:1 · одна попыткаКопировать промпт

07Где эти советы не помогут?

• Лимиты общие для аккаунта. Другие ключи и сервисы расходуют те же 120 запросов и 100 мест, а очередь одного сервиса не видит, сколько заняли другие: заложите запас и договоритесь о долях.
• Блокировка за ошибки доступа — не про частоту. При burst_block одной паузы мало: сначала устраните причину отказов.
• Готового расписания повторов нет. Документация задаёт правило: не меньше Retry-After и случайная добавка. Примеры в ней берут три или пять попыток, а число для вашего сервиса выбираете вы.
• Рекомендованного числа заданий в работе тоже нет. Предел — 100 на аккаунт, а сколько занимать, зависит от ваших процессов.
• Три кадра статьи ничего не измеряют. Это обычные успешные результаты: по ним нельзя судить ни о скорости, ни о нагрузке.

08Вопросы и ответы

09Источники

1. Документация Rendergrid: лимитыПределы по умолчанию, примеры ответов 429 и повтор с паузой.
2. Документация Rendergrid: коды ошибокФормат ошибки, коды ERR_RATE_LIMIT и ERR_QUOTA_EXCEEDED, заголовок Retry-After.
3. Документация Rendergrid: задачи и статусыКак часто опрашивать задание и сколько хранятся файлы.
4. Документация Rendergrid: вебхукиПодпись, повторы доставки и время ответа.
5. Документация Rendergrid: повтор без двойного списанияКлюч повтора и повтор после 429.