Genuka WA docs

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

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

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). 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).

Cuatro límites, cuatro códigos

CódigoQué se cuentaAlcance
4Las llamadas a la API de la aplicaciónToda la aplicación
80007Las 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 registradoUna app y una cuenta de WhatsApp
130429Mensajes por segundo: 80 de forma predeterminadaUn número
131056Mensajes al mismo destinatario: uno cada 6 segundosUn par remitente-destinatario

Las cifras provienen de la descripción general de la plataforma de Meta (Meta, About the platform).

¿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.

CanalLo que recibes
POST /api/v1/messages400, "error": "send_retryable", meta.code: 4, meta.retryable: true
CampañaCada 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/templates422, "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). 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?

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.

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; 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).

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).

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));
  }
}

¿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.
  • 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: el límite de llamadas de una app sobre una cuenta de WhatsApp.
  • 130429: el rendimiento de mensajes por segundo de un número.
  • 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

En esta página