Error 429 y límites: cómo evitarlo al generar

01¿Qué significa un error 429?

El 429 («Too Many Requests») no es una tarea fallida: una tarea aceptada que no llegó a producir imagen aparece en GET /creations/{id} con el estado failed. Un 429 responde a una solicitud que la API no atendió porque superaste un límite. Hay tres casos principales:

• Demasiadas solicitudes por minuto. Son 120 por minuto, en ventanas de 60 segundos, para toda la cuenta. Al superarlo llega 429 ERR_RATE_LIMIT con details.limit, details.window = "1m" y details.retry_after.

• Demasiadas tareas a la vez. La cuenta admite 100 tareas en cola o en proceso. Al superarlo llega 429 ERR_QUOTA_EXCEEDED con details.scope = "account".

• Consultas de estado demasiado seguidas. Una misma clave puede consultar una misma tarea una vez cada 5 segundos como máximo. Una consulta anterior a ese plazo recibe 429 ERR_RATE_LIMIT con details.min_interval_seconds.

Así llegan las respuestas de los dos primeros casos. Los valores de Retry-After son de ejemplo: léelos en cada respuesta.

Retry-After: 17

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

Retry-After: 2

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

El texto de message está en inglés y puede cambiar: decide con el estado HTTP, code y details.

02¿Cuántas solicitudes enviar a la vez?

Hay dos topes, ambos de la cuenta y no de cada clave: abrir más claves de API no los amplía.

El primero son las tareas simultáneas: hasta 100 en cola o en proceso, y cada una ocupa su lugar hasta que termina. La documentación recomienda mantener tu propia cola y lanzar las tareas nuevas a medida que se liberan lugares, en lugar de enviarlas todas de golpe. Fija un máximo menor que 100 y deja margen si más de un programa usa la cuenta: comparten el mismo cupo.

El segundo es la frecuencia: 120 solicitudes por minuto equivalen a una cada 0,5 segundos de media. Entran en ese recuento el inicio de generaciones, la carga de archivos, la lectura del catálogo y la del saldo; la consulta de estado se cuenta aparte.

Prompt: cubos de madera en fila

Cinco cubos de madera idénticos en una fila horizontal recta sobre gris claro. Mantén intervalos iguales y caras frontales alineadas. Cámara un poco elevada, luz suave desde la izquierda, todos los cubos completos y márgenes amplios. Sin texto, logotipos, personas ni marcas de agua.

1K, 1:1, un intentoCopiar prompt

03¿Cómo reintentar después de un 429?

Espera y repite el mismo envío. La receta tiene cuatro pasos:

1. Espera como mínimo Retry-After segundos. Las respuestas 429 traen ese encabezado.
2. Añade un pequeño retardo aleatorio, para que varios procesos no repitan a la vez.
3. Limita el número de intentos y, si el último también recibe un 429, devuélvelo a tu código.
4. Repite el mismo cuerpo con la misma clave de API y la misma clave de idempotencia (X-Idempotency-Key): así no se crea una segunda tarea.

Si repites el envío mientras el primero aún se está aceptando, puede llegar un 429 con details.reason: idempotency_in_flight: espera y vuelve a enviar con la misma clave. Si el primero ya se aceptó, repetirlo con la misma clave devuelve la misma respuesta 202, con los mismos id, status, task_id y cost. Es la respuesta guardada, no el estado actual: puede decir queued aunque la imagen ya esté lista.

Una tarea que pasó de 202 a failed no se reinicia con la misma clave: un intento nuevo es una solicitud nueva, con una clave nueva y una operación nueva de pago; el cargo anterior se devuelve por sí solo.

El ejemplo hace como máximo cinco intentos, como el de la documentación de límites; elige tú el tope. Se detiene ante details.reason: burst_block, porque antes hay que corregir la causa de los errores 401 y 403.

# Hacen falta bash, curl y uuidgen. La clave de idempotencia se crea una sola vez por operación.
IDEMPOTENCY_KEY="$(uuidgen)" || exit 1
# -i muestra el estado y los encabezados: en un 429 verás Retry-After
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": "Taza de cerámica sobre mármol, luz suave de ventana",
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }'
# con un 429, espera Retry-After segundos y repite este mismo comando con el mismo IDEMPOTENCY_KEY

import os
import random
import time
import uuid

import requests

API = "https://api.rendergrid.io/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['RENDERGRID_API_KEY']}"}


def submit(payload, max_attempts=5):
    # una clave nueva por imagen; la misma en todos los reintentos de esa imagen
    headers = {**HEADERS, "X-Idempotency-Key": str(uuid.uuid4())}
    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:
            reason = response.json()["error"]["details"].get("reason")
        except (ValueError, KeyError, TypeError, AttributeError):
            reason = None
        if reason == "burst_block" or attempt + 1 == max_attempts:
            # con burst_block no reintentes: corrige antes la causa
            return response
        wait = response.headers.get("Retry-After", "")
        seconds = int(wait) if wait.isascii() and wait.isdigit() else 2
        # como mínimo Retry-After, más un pequeño retardo aleatorio
        time.sleep(seconds + random.uniform(0, 1))


response = submit(
    {
        "model": "nano-banana-2.1",
        "prompt": "Taza de cerámica sobre mármol, luz suave de ventana",
        "resolution": "1K",
        "aspect_ratio": "1:1",
    }
)
print(response.status_code, response.json())

// Node.js 22+, archivo .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 submit(payload, maxAttempts = 5) {
  // una clave nueva por imagen; la misma en todos los reintentos de esa imagen
  const idempotencyKey = randomUUID();
  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(() => ({}));
    if (body?.error?.details?.reason === "burst_block" || attempt + 1 === maxAttempts) {
      // con burst_block no reintentes: corrige antes la causa
      return response;
    }
    const wait = response.headers.get("Retry-After");
    const seconds = wait && /^[0-9]+$/.test(wait) ? Number(wait) : 2;
    // como mínimo Retry-After, más un pequeño retardo aleatorio
    await sleep((seconds + Math.random()) * 1000);
  }
}

const response = await submit({
  model: "nano-banana-2.1",
  prompt: "Taza de cerámica sobre mármol, luz suave de ventana",
  resolution: "1K",
  aspect_ratio: "1:1",
});
console.log(response.status, await response.json());

El ejemplo no espera el resultado: eso está en la documentación de tareas y estados.

04¿Cada cuánto consultar el estado de una tarea?

Una misma clave puede consultar una misma tarea con GET /creations/{id} una vez cada 5 segundos como máximo. Ante un 429 con details.min_interval_seconds, espera el mayor entre ese valor y Retry-After: el encabezado a veces indica un intervalo menor.

Deja de consultar cuando el estado sea completed o failed, y limita el tiempo total de espera: si se agota, guarda el id y continúa más tarde, porque el tiempo de espera agotado de tu cliente no cancela la tarea.

La documentación no promete un plazo para el resultado: depende del modelo y de la carga. Con 100 tareas en proceso y una consulta cada 5 segundos por tarea, son 20 consultas por segundo.

Prompt: nueve tacitas en cuadrícula

Vista cenital de nueve tacitas blancas de cerámica sin asa, ordenadas en una cuadrícula de tres por tres. Espacios uniformes y bocas del mismo tamaño. Fondo beige mate, iluminación suave pareja y sombras finas; deja un marco vacío alrededor del conjunto. Sin texto, logotipos, personas ni marcas de agua.

1K, 1:1, un intentoCopiar prompt

05¿Cuándo usar webhooks en lugar de consultar?

Con muchas tareas, las consultas se multiplican. Con un webhook no consultas: indica webhook_url en cada solicitud de generación y la API envía un POST firmado a esa dirección cuando la tarea pasa a completed o failed.

• La dirección. HTTPS pública, de hasta 2 048 caracteres; si es incorrecta o está prohibida, la solicitud devuelve 400 antes del cargo.

• La firma. X-Webhook-Signature-256 es un HMAC-SHA256 de X-Timestamp, un punto y el cuerpo original. Compruébala antes de actuar.

• La respuesta. Responde con un 2xx en menos de 10 segundos.

• Los reintentos. Sin un 2xx, repetimos la entrega hasta cinco intentos en total, con esperas de 60, 120, 240 y 480 segundos.

La entrega no está garantizada al cien por cien: conserva la consulta de estado como respaldo. Y un webhook no sustituye al tope de 100 tareas simultáneas. Más detalles en la documentación de webhooks y en la guía sobre lotes, webhooks e idempotencia.

06¿Qué recibes cuando la tarea termina?

Una tarea completed trae result_urls, los enlaces a los archivos. Descarga la imagen a tu almacenamiento enseguida: los archivos se conservan un día y consultar la tarea no prolonga ese plazo. Una tarea failed trae failure con type, code y retryable, y el importe cargado vuelve al saldo por sí solo.

Prompt: cinco frascos en arco

Cinco frascos crema iguales, cerrados, forman un arco suave sobre fondo arena. Vista algo elevada, separaciones uniformes y tapas redondas lisas. La luz suave de la derecha genera sombras individuales. No cortes los frascos y deja vacío el centro del arco. Sin texto, logotipos, personas ni marcas de agua.

1K, 1:1, un intentoCopiar prompt

Las tres imágenes de este artículo son resultados de tareas completadas con Nano Banana 2.1, un intento cada una. No son pantallas de error ni miden velocidad o carga.

07¿Qué no cubre este artículo?

• Son los valores predeterminados. El límite de una cuenta puede ser otro: si te queda corto, escribe a soporte con la cuenta y el volumen que necesitas.
• No todos los 429 son de volumen. Una cuenta que se registró sola y no ha recargado el saldo puede usar 100 imágenes de referencia por día: recarga el saldo o espera al día siguiente. Y 30 errores 401 o 30 errores 403 en un minuto bloquean la IP hasta 120 segundos (burst_block): corrige antes la causa.
• Un 429 no es un 402. Sin saldo suficiente, o con el límite mensual agotado, la respuesta es 402 ERR_INSUFFICIENT_BALANCE.
• Un rechazo por las reglas de contenido no se arregla con una pausa. Llega como una tarea failed con failure.type: declined: cambia la solicitud.

08Preguntas frecuentes

09Fuentes

1. LímitesLos valores predeterminados, las respuestas 429 y el ejemplo de reintentos.
2. Códigos de errorEl formato del error, Retry-After y las tareas con estado failed.
3. Tareas y estadosLa frecuencia de las consultas de estado y los archivos del resultado.
4. WebhooksLa firma, la respuesta y los reintentos de las entregas.
5. Reintentos sin doble cargoLa clave de idempotencia y lo que devuelve un reintento.