# Error 130429 de WhatsApp: Rate limit hit — causa y solución

URL: https://wa.genuka.com/es/docs/errors/130429
Language: Spanish

> El error 130429 de WhatsApp (Rate limit hit) significa que tu número superó su capacidad de envío en la Cloud API. Los límites por número y cómo reintentar sin perder mensajes.

El error 130429 de WhatsApp significa que tu número superó su capacidad de envío en la Cloud API
de Meta: 80 mensajes por segundo de forma predeterminada, 20 para un número en coexistencia con la
aplicación WhatsApp Business. No hay nada roto. Reduce el ritmo, reintenta con una espera creciente
y distribuye los envíos grandes en el tiempo en lugar de lanzarlos todos a la vez.

## ¿Qué significa el error 130429?

Meta lo clasifica entre los errores de límite de velocidad:

> "Cloud API message throughput has been reached."
> — [Meta, códigos de error de la Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#throttling-errors)

Dicho de otro modo, el número agotó la cantidad de mensajes por segundo que tiene permitida. En la
respuesta de Graph, el campo `message` combina el código y su título: `(#130429) Rate limit hit`.
Meta advierte que estos títulos dejarán de usarse en algún momento, así que basa tu gestión en el
código, nunca en el texto.

La capacidad de envío se cuenta **por número** e incluye los mensajes entrantes y salientes de
todos los tipos
([Meta, Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)):

| Número                                                                    | Capacidad máxima       |
| ------------------------------------------------------------------------- | ---------------------- |
| Número estándar de la Cloud API                                           | 80 mensajes/s          |
| Número mejorado automáticamente por Meta                                  | hasta 1.000 mensajes/s |
| Número en coexistencia (también usado en la aplicación WhatsApp Business) | 20 mensajes/s, fijo    |

Meta sigue devolviendo 130429 hasta que vuelvas a estar por debajo de ese techo.

## ¿Cuándo aparece el error 130429?

* **Un bucle de envío sin control de ritmo**: un script que recorre una lista de 10.000 contactos
  tan rápido como lo permite la red supera los 80 mensajes/s en cuestión de instantes.
* **Un número en coexistencia**: el tope de 20 mensajes/s se aplica sea cual sea tu nivel. Una
  campaña de 100.000 destinatarios tarda en él al menos 83 minutos.
* **Varios emisores en un mismo número**: dos procesos, dos campañas o un flujo de llamadas a la
  API que corre junto a una campaña comparten la misma capacidad sin coordinarse.
* **Un pico de mensajes entrantes**: cuentan contra la misma capacidad que tus envíos.

No confundas el 130429 con otros dos techos:

| Techo              | Qué cuenta                                                                                             | Código                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| Capacidad de envío | Mensajes por segundo, por número                                                                       | `130429`                                                                                                                      |
| Límite por par     | Mensajes al **mismo** destinatario                                                                     | [`131056`](https://wa.genuka.com/es/docs/errors/131056)                                                                                            |
| Límite de mensajes | Destinatarios únicos fuera de la ventana de servicio en 24 h móviles, a nivel del portafolio comercial | consulta [Meta, Messaging limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits) |

### ¿Dónde lo ves en Genuka WA?

| Canal                                | Qué recibes                                                                     |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| Respuesta de `POST /api/v1/messages` | `400`, `"error": "send_retryable"`, `meta.code: 130429`, `meta.retryable: true` |
| Campaña                              | Cada destinatario se reintenta; solo pasa a `failed` después de tres intentos   |
| Panel, sección Registros             | La solicitud rechazada, con el cuerpo de la respuesta                           |

```json title="400 — respuesta de POST /api/v1/messages"
{
  "error": "send_retryable",
  "message": "Cloud API message throughput has been reached.",
  "meta": {
    "errorClass": "retryable",
    "retryable": true,
    "code": 130429,
    "details": "Cloud API message throughput has been reached.",
    "traceId": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}
```

El estado HTTP es `400`, no `429`: decide si reintentar a partir de `meta.retryable`, no del
estado.

## ¿Cómo corrijo el error 130429?

1. **Reintenta con una espera creciente.** Genuka WA nunca reintenta por ti un envío individual hecho
   con `POST /api/v1/messages`: una solicitud interactiva no debería tardar varios segundos en fallar
   en silencio. Tu código reintenta, con una espera que se duplica en cada intento más un poco de
   variación aleatoria (jitter) para que tus procesos no se reinicien todos en el mismo milisegundo.
2. **Mide tu techo real.** `GET /api/v1/numbers` devuelve, para cada número, un campo
   `messagesPerSecond` (20, 80 o 1.000) y `coexistence: true` cuando el número también se usa en la
   aplicación. Ajusta el ritmo de tus envíos a ese valor, no a un valor predeterminado de 80.
3. **Haz los envíos masivos con una campaña.** `POST /api/v1/campaigns` y luego
   `/api/v1/campaigns/{id}/launch`: Genuka WA ajusta el ritmo a la capacidad del número y hace hasta
   tres intentos por destinatario (esperas de 500 ms como máximo, luego 1 s, con variación aleatoria).
   Un 130429 puntual no te hace perder al destinatario. Consulta la
   [guía de la API de campañas](https://wa.genuka.com/es/docs/guides/campaigns-api).

**Node.js**

```ts
const API = "https://wa.genuka.com/api/v1";

export async function sendWithBackoff(payload: unknown, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(`${API}/messages`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });
    // Un 5xx puede llegar como texto plano ("error code: 502" del proxy): el JSON no está garantizado.
    const json = await response.json().catch(() => null);
    if (response.ok) return json?.data; // { messageId, warning? }

    // meta.retryable es true para los límites de velocidad (130429, 131056, 4, 80007), los errores
    // internos de Meta (131000, 5xx), los medios caducados y el 131048. Este último se reintenta más
    // tarde, no en este bucle (consulta la página del 131048). Un 5xx sin `meta` no indica si el
    // mensaje salió: se lanza tal cual, verifica antes de reenviar para evitar un duplicado.
    const retryable = json?.meta?.retryable === true && json.meta.code !== 131048;
    if (!retryable || attempt >= maxAttempts) {
      throw new Error(`${response.status} ${json?.error ?? ""}: ${json?.message ?? ""}`);
    }
    const base = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
    await new Promise((resolve) => setTimeout(resolve, base / 2 + Math.random() * (base / 2)));
  }
}
```

**Python**

```python
import os
import random
import time

import requests

API = "https://wa.genuka.com/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}",
    "User-Agent": "acme-crm/1.0 (+https://example.com)",
}


def send_with_backoff(payload, max_attempts=5):
    for attempt in range(1, max_attempts + 1):
        response = requests.post(f"{API}/messages", json=payload, headers=HEADERS, timeout=30)
        try:
            body = response.json()
        except ValueError:  # un 5xx del proxy puede llegar como texto plano
            body = {}
        if response.ok:
            return body["data"]  # {"messageId": ..., "warning": ...}

        meta = body.get("meta", {})
        # 131048 es reintentable, pero más tarde: consulta la página del 131048. Un 5xx sin `meta`
        # no indica si el mensaje salió: se lanza tal cual, verifica antes de reenviar.
        retryable = meta.get("retryable", False) and meta.get("code") != 131048
        if not retryable or attempt == max_attempts:
            raise RuntimeError(f"{response.status_code} {body.get('error')}: {body.get('message', '')}")
        base = min(30.0, 2 ** (attempt - 1))
        time.sleep(base / 2 + random.random() * base / 2)
```

**PHP**

```php
<?php
function send_with_backoff(array $payload, int $maxAttempts = 5): array
{
    for ($attempt = 1; ; $attempt++) {
        $ch = curl_init("https://wa.genuka.com/api/v1/messages");
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_USERAGENT => "acme-crm/1.0 (+https://example.com)",
            CURLOPT_HTTPHEADER => [
                "Authorization: Bearer " . getenv("GENUKA_WA_API_KEY"),
                "Content-Type: application/json",
            ],
            CURLOPT_POSTFIELDS => json_encode($payload),
        ]);
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);
        // Un 5xx del proxy puede llegar como texto plano: el JSON no está garantizado.
        $json = is_string($raw) ? json_decode($raw, true) : null;
        $json = is_array($json) ? $json : [];

        if ($status >= 200 && $status < 400) {
            return $json["data"];
        }
        $meta = $json["meta"] ?? [];
        // 131048: más tarde (consulta su página). Un 5xx sin "meta" se lanza tal cual: verifica
        // antes de reenviar, el mensaje puede haber salido.
        $retryable = ($meta["retryable"] ?? false) && ($meta["code"] ?? null) !== 131048;
        if (!$retryable || $attempt >= $maxAttempts) {
            throw new RuntimeException("{$status} " . ($json["error"] ?? ""));
        }
        $base = min(30.0, 2 ** ($attempt - 1));
        usleep((int) (($base / 2 + mt_rand() / mt_getrandmax() * $base / 2) * 1_000_000));
    }
}
```

**curl**

```bash
# La capacidad de envío de cada número, para ajustar el ritmo de tus envíos (valores almacenados).
# Para volver a leerlos desde Meta: ?refresh=true&companyId=..., 25 números como máximo por llamada.
curl "https://wa.genuka.com/api/v1/numbers" \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY"
# { "data": [ { "id": "con_1", "messagesPerSecond": 80, "coexistence": false, ... } ] }
```

## ¿Cómo evito el error 130429?

* **Un solo emisor por número.** Pasa todos los envíos de un número por una única cola, con un
  ritmo por debajo de `messagesPerSecond`. Eso es lo que evita que dos procesos se pisen.
* **Planifica la duración de los envíos grandes.** A 20 mensajes/s, un número en coexistencia envía
  como máximo 72.000 mensajes por hora. Anuncia la duración en lugar de descubrirla.
* **Usa medios alojados por Meta** para los envíos rápidos: Meta recomienda enviar un ID de medio en
  lugar de una URL en tus propios servidores para aprovechar una mayor capacidad de envío
  ([Meta, Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)).
  Con Genuka WA, `assetId` hace exactamente eso.
* **No reintentes a intervalos fijos.** Un bucle de "tres intentos, con un segundo de diferencia"
  envía la misma ráfaga en el mismo momento y recibe otro 130429.

## Códigos de error relacionados

* [131056](https://wa.genuka.com/es/docs/errors/131056): demasiados mensajes al **mismo** destinatario en poco tiempo.
* [131048](https://wa.genuka.com/es/docs/errors/131048): envíos restringidos tras bloqueos o reportes de spam, un
  problema de calidad más que de velocidad.
* [4](https://wa.genuka.com/es/docs/errors/4) y [80007](https://wa.genuka.com/es/docs/errors/80007): los otros dos límites de la misma
  familia, que cuentan **llamadas a la API** de la aplicación y de la cuenta de WhatsApp Business,
  no mensajes enviados.

## Preguntas frecuentes

### ¿Mi número puede llegar a 1.000 mensajes por segundo?

Sí, de forma automática y sin costo, cuando se cumplen tres condiciones: un límite de mensajes
ilimitado, al menos 100.000 usuarios únicos contactados fuera de una ventana de servicio en 24
horas móviles, y una calificación de calidad de al menos media. Durante la mejora, que tarda hasta
un minuto, el número responde `131057`
([Meta, Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)).
Un número en coexistencia se queda en 20 mensajes/s.

### ¿Meta cobra un mensaje rechazado con 130429?

No. Meta solo cobra un mensaje de plantilla cuando se entrega
([Meta, Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)),
y un mensaje rechazado con 130429 nunca salió. Del lado de Genuka WA, un envío rechazado tampoco
consume la cuota de tu suscripción: solo se cuentan los mensajes que Meta aceptó.

### ¿Por qué Genuka WA responde 400 y no 429?

Porque todos los rechazos de Meta en un envío vuelven como `400`, salvo los problemas de token, de
permisos y de registro del número, que vuelven como `409`. Si conviene reintentar lo indican
`meta.retryable` y `meta.errorClass`, que existen para eso.

### ¿El 130429 puede venir de la propia API de Genuka WA?

No. El 130429 es un código de Meta que Genuka WA transmite tal cual en `meta.code`: siempre se
refiere a la capacidad de envío del número emisor en Meta, no a tu clave API.

## Fuentes

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)
* [Meta — Messaging limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)
* [Meta — Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
* [Meta — About the platform, rate limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#rate-limits)
