# Error 4 de WhatsApp: límite de velocidad de la app alcanzado — solución

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

> Error 4 de WhatsApp (API Too Many Calls): la app alcanzó su límite de velocidad de llamadas a la API de Meta. En qué se diferencia de 80007 y 130429, y cómo reintentar sin riesgo.

El error 4 de WhatsApp significa que la aplicación que llama a la API de Meta alcanzó su límite de velocidad de llamadas. Es una
limitación temporal: nada está roto, tienes que esperar y enviar menos solicitudes. Se aplica a la
aplicación en su conjunto, no a un número ni a una cuenta de WhatsApp, y eso es lo que lo distingue de
los errores 80007 y 130429.

## ¿Qué significa el error 4?

Meta lo clasifica entre los errores de limitación (throttling) de la Cloud API:

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

La solución sugerida: abrir la app en el App Dashboard, sección **Application Rate Limit**, confirmar
que se alcanzó el límite y luego volver a intentarlo más tarde o reducir la frecuencia y la cantidad de solicitudes. La
documentación de Graph llama a este código "API Too Many Calls", un problema temporal de limitación: "Wait and
retry the operation, or examine your API request volume" (espera y reintenta la operación, o examina tu volumen de solicitudes a la API)
([Meta, Graph API, manejo de errores](https://developers.facebook.com/docs/graph-api/guides/error-handling)).
Su página sobre límites de velocidad agrega que el código 4 significa que la app cuyo token se usa en la solicitud alcanzó
su límite ([Meta, Rate limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting)).

### Cuatro límites, cuatro códigos

| Código                           | Qué se cuenta                                                                                                                                   | Alcance                          |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| **4**                            | Las llamadas a la API de la aplicación                                                                                                          | Toda la aplicación               |
| [80007](https://wa.genuka.com/es/docs/errors/80007)   | Las llamadas de una app sobre una cuenta de WhatsApp: 200 por hora de forma predeterminada, 5.000 en una cuenta activa con un número registrado | Una app y una cuenta de WhatsApp |
| [130429](https://wa.genuka.com/es/docs/errors/130429) | Mensajes por segundo: 80 de forma predeterminada                                                                                                | Un número                        |
| [131056](https://wa.genuka.com/es/docs/errors/131056) | Mensajes al mismo destinatario: uno cada 6 segundos                                                                                             | Un par remitente-destinatario    |

Las cifras provienen de la descripción general de la plataforma de Meta
([Meta, About the platform](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#rate-limits)).

## ¿Cuándo ocurre el error 4?

* **Una ráfaga de llamadas que no son envíos**: listar plantillas en bucle, volver a leer el estado de cada número
  en cada carga del panel, subir archivos multimedia uno tras otro.
* **Varios servicios en la misma app**: un worker de campañas, un back office y un script de sincronización que comparten
  un mismo token suman sus llamadas.
* **Un bucle de reintentos sin espera**: cada fallo dispara otra llamada de inmediato, y el límite se aleja
  en lugar de acercarse.

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

Con Genuka WA, la aplicación de Meta que hace la llamada es la de Genuka, como Tech Provider: el
límite de la aplicación no depende solo de tu volumen. Genuka coloca el código 4 en la clase
`retryable`.

| Canal                    | Lo que recibes                                                                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/v1/messages`  | `400`, `"error": "send_retryable"`, `meta.code: 4`, `meta.retryable: true`                                                                         |
| Campaña                  | Cada destinatario tiene hasta tres intentos en total (dos reintentos), con esperas de 0.25 a 0,5 s y luego de 0.5 a 1 s, antes de pasar a `failed` |
| `POST /api/v1/templates` | `422`, `"error": "meta_rejected"`, `meta.retryable: true` si Meta respondió con un 4xx; `502` si respondió 429 o 5xx                               |

Ese `502` llega sin cuerpo JSON: nuestra CDN reemplaza la respuesta por la única línea
`error code: 502` ([referencia de la API](https://wa.genuka.com/es/docs/api)). Trátalo como un fallo transitorio, sin
buscar `meta` en él.

Genuka también limita las ráfagas que podría provocar en tu nombre: `GET /api/v1/numbers?refresh=true`
rechaza la llamada (`400 too_many_connections`) por encima de 25 números, así que acótala con `?companyId=`;
y una actualización de plantillas procesa las cuentas de WhatsApp de cinco en cinco.

## ¿Cómo corrijo el error 4?

1. **Reintenta con una espera creciente, solo cuando `meta.retryable` sea `true`** o ante un `5xx` sin cuerpo
   JSON. Genuka WA no reintenta un envío individual por ti: tu código tiene que esperar, duplicando la
   espera en cada intento y agregando un poco de aleatoriedad para que tus workers no se reinicien todos a la vez.

   Para un envío, reintenta solo cuando `meta.code` esté presente (4, 80007, 130429…). Un tiempo de espera agotado entre Genuka
   y Meta también se marca como `retryable`, sin `meta.code`, aunque Meta ya podría haber
   aceptado el mensaje; la API no tiene clave de idempotencia, y volver a enviarlo puede entregarlo dos veces.

2. **Elimina las llamadas de lectura innecesarias.** `GET /api/v1/numbers` sin `refresh=true` devuelve el estado
   guardado, que los webhooks de Meta mantienen actualizado. Los estados de las plantillas llegan por [webhook](https://wa.genuka.com/es/docs/webhooks);
   la actualización `POST /api/v1/templates/sync` es una vía de reparación, y una vez por hora es más que suficiente
   ([referencia de la API](https://wa.genuka.com/es/docs/api#plantillas)).

3. **Si el error dura más de una hora**, contacta al soporte de Genuka con el encabezado `x-request-id` y
   `meta.traceId`: los límites de Graph se cuentan sobre una hora móvil.

Si llamas a la Cloud API con tu propia app, el App Dashboard muestra el uso actual del Application
Rate Limit de la app y la cantidad de usuarios limitados
([Meta, Rate limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting)).

**Node.js**

```ts
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

export async function callGenuka(path: string, body: unknown, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(`https://wa.genuka.com/api/v1${path}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    // Un 5xx llega sin JSON: nuestra CDN lo reemplaza por "error code: 502".
    const json = await response.json().catch(() => null);
    if (response.ok) return json.data;

    // Un envío solo se reintenta ante un código de Meta (4, 80007, 130429…): tras un tiempo de espera agotado,
    // Meta ya podría haber aceptado el mensaje, y volver a enviarlo lo entregaría dos veces.
    const retryable =
      path === "/messages"
        ? json?.meta?.retryable === true && json.meta.code !== undefined
        : response.status >= 500 || json?.meta?.retryable === true;
    if (!retryable || attempt >= maxAttempts) {
      throw new Error(`${response.status} ${json?.error ?? "sin cuerpo JSON"} (Meta ${json?.meta?.code ?? "-"})`);
    }
    const base = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
    await sleep(base / 2 + Math.random() * (base / 2));
  }
}
```

**Python**

```python
import os
import random
import time
import requests

def call_genuka(path: str, body: dict, max_attempts: int = 5) -> dict:
    for attempt in range(1, max_attempts + 1):
        response = requests.post(
            f"https://wa.genuka.com/api/v1{path}",
            headers={"Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}"},
            json=body,
            timeout=30,
        )
        try:
            payload = response.json()
        except ValueError:
            # Un 5xx llega sin JSON: nuestra CDN lo reemplaza por "error code: 502".
            payload = {}
        if response.ok:
            return payload["data"]
        meta = payload.get("meta") or {}
        # Un envío solo se reintenta ante un código de Meta (4, 80007, 130429…): tras un tiempo de espera agotado,
        # Meta ya podría haber aceptado el mensaje, y volver a enviarlo lo entregaría dos veces.
        if path == "/messages":
            retryable = bool(meta.get("retryable")) and meta.get("code") is not None
        else:
            retryable = response.status_code >= 500 or bool(meta.get("retryable"))
        if not retryable or attempt == max_attempts:
            raise RuntimeError(f"{response.status_code} {payload.get('error', 'sin cuerpo JSON')} (Meta {meta.get('code')})")
        base = min(30.0, 2 ** (attempt - 1))
        time.sleep(base / 2 + random.random() * base / 2)
```

**PHP**

```php
<?php
function callGenuka(string $path, array $body, int $maxAttempts = 5): array
{
    for ($attempt = 1; ; $attempt++) {
        $ch = curl_init("https://wa.genuka.com/api/v1" . $path);
        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($body),
        ]);
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 0 cuando la solicitud nunca terminó
        curl_close($ch);
        // Un 5xx llega sin JSON: nuestra CDN lo reemplaza por "error code: 502".
        $json = is_string($raw) ? json_decode($raw, true) : null;
        if (!is_array($json)) $json = [];

        if ($status >= 200 && $status < 300) return $json["data"];
        // Un envío solo se reintenta ante un código de Meta (4, 80007, 130429…): tras un tiempo de espera agotado,
        // Meta ya podría haber aceptado el mensaje, y volver a enviarlo lo entregaría dos veces.
        $meta = $json["meta"] ?? [];
        $retryable = $path === "/messages"
            ? !empty($meta["retryable"]) && isset($meta["code"])
            : $status === 0 || $status >= 500 || !empty($meta["retryable"]);
        if (!$retryable || $attempt >= $maxAttempts) {
            throw new RuntimeException("$status " . ($json["error"] ?? "sin cuerpo JSON") . " (Meta " . ($meta["code"] ?? "-") . ")");
        }
        $base = min(30.0, 2 ** ($attempt - 1));
        usleep((int) (($base / 2 + mt_rand() / mt_getrandmax() * $base / 2) * 1_000_000));
    }
}
```

**curl**

```bash
# Un solo intento: lee meta.retryable antes de decidir volver a intentarlo.
curl -s -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectionId": "con_1", "to": "+237690000001", "text": "Tu paquete está en camino." }' \
  | jq '{error, code: .meta.code, retryable: .meta.retryable}'
```

## ¿Cómo evito el error 4?

* **Prefiere los webhooks a la consulta periódica (polling).** Los estados de los mensajes, las revisiones de plantillas y los cambios de calidad llegan
  por sí solos; pedirlos en bucle consume el límite para nada.
* **Haz los envíos masivos mediante una campaña.** Genuka ajusta el ritmo del envío al rendimiento del número y gestiona
  los reintentos destinatario por destinatario — consulta [campañas por API](https://wa.genuka.com/es/docs/guides/campaigns-api).
* **Nunca reintentes a intervalo fijo.** Tres intentos con un segundo de diferencia repiten la misma ráfaga en el
  mismo momento.

## Códigos de error relacionados

* [80007](https://wa.genuka.com/es/docs/errors/80007): el límite de llamadas de una app sobre una cuenta de WhatsApp.
* [130429](https://wa.genuka.com/es/docs/errors/130429): el rendimiento de mensajes por segundo de un número.
* [131056](https://wa.genuka.com/es/docs/errors/131056): demasiados mensajes al mismo destinatario en poco tiempo.

## Preguntas frecuentes

### ¿El error 4 viene de mi clave API de Genuka?

No. Es un código de Meta, transmitido en `meta.code`. Concierne a la aplicación de Meta que hace la llamada,
la de Genuka, no a tu clave.

### ¿Cuánto tiempo debo esperar?

Meta no da una duración fija para el código 4: los límites de Graph se calculan sobre una hora móvil. Empieza con una
espera creciente, de uno a treinta segundos, y reduce tus llamadas; si el error dura más de una
hora, avisa al soporte.

### ¿Se cobra un mensaje rechazado con el código 4?

Meta no lo aceptó, así que no hay ningún mensaje que cobrar. Del lado de Genuka WA, solo los mensajes que Meta
aceptó cuentan en la cuota de tu plan.

## Fuentes

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Graph API, Handling errors](https://developers.facebook.com/docs/graph-api/guides/error-handling)
* [Meta — Graph API, Rate limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting)
* [Meta — About the platform, rate limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#rate-limits)
