# Errore WhatsApp 130429: Rate limit hit — causa e soluzione

URL: https://wa.genuka.com/it/docs/errors/130429
Language: Italian

> L'errore WhatsApp 130429 (Rate limit hit) significa che il tuo numero ha superato il suo throughput sulla Cloud API. I limiti per numero e come riprovare senza perdere messaggi.

L'errore WhatsApp 130429 significa che il tuo numero ha superato il suo throughput di invio sulla Cloud API di Meta:
80 messaggi al secondo di default, 20 per un numero in coesistenza con l'app WhatsApp Business.
Non c'è niente di rotto. Rallenta, riprova con un ritardo crescente e distribuisci gli invii grandi nel tempo
invece di sparare tutto in una volta.

## Cosa significa l'errore 130429?

Meta lo classifica tra gli errori di throttling:

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

In altre parole, il numero ha esaurito la frequenza di messaggi consentita. Nella risposta Graph, il campo
`message` combina il codice e il suo titolo: `(#130429) Rate limit hit`. Meta avverte che questi
titoli prima o poi saranno deprecati, quindi basa la tua gestione sul codice, mai sul testo.

Il throughput si conta **per numero** e include i messaggi in entrata e in uscita di ogni tipo
([Meta, Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)):

| Numero                                                         | Throughput massimo      |
| -------------------------------------------------------------- | ----------------------- |
| Numero Cloud API standard                                      | 80 messaggi/s           |
| Numero aggiornato automaticamente da Meta                      | fino a 1.000 messaggi/s |
| Numero in coesistenza (usato anche nell'app WhatsApp Business) | 20 messaggi/s, fisso    |

Meta continua a restituire 130429 finché non torni sotto quel tetto.

## Quando si verifica l'errore 130429?

* **Un ciclo di invio senza ritmo**: uno script che scorre una lista di 10.000 contatti alla massima velocità
  consentita dalla rete supera gli 80 messaggi/s in pochi istanti.
* **Un numero in coesistenza**: il limite di 20 messaggi/s vale qualunque sia il tuo livello. Una campagna
  da 100.000 destinatari richiede almeno 83 minuti su quel numero.
* **Più mittenti su un solo numero**: due worker, due campagne o un flusso di chiamate API in esecuzione
  accanto a una campagna condividono lo stesso throughput senza coordinarsi.
* **Un picco di messaggi in entrata**: contano sullo stesso throughput dei tuoi invii.

Non confondere 130429 con altri due tetti:

| Tetto                          | Cosa conta                                                                                           | Codice                                                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Throughput                     | Messaggi al secondo, per numero                                                                      | `130429`                                                                                                                  |
| Limite di frequenza per coppia | Messaggi verso **lo stesso** destinatario                                                            | [`131056`](https://wa.genuka.com/it/docs/errors/131056)                                                                                        |
| Limite di messaggistica        | Destinatari unici fuori dalla finestra di servizio su 24 h mobili, a livello di portafoglio business | vedi [Meta, Messaging limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits) |

### Dove lo vedi in Genuka WA?

| Canale                              | Cosa ottieni                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------- |
| Risposta di `POST /api/v1/messages` | `400`, `"error": "send_retryable"`, `meta.code: 130429`, `meta.retryable: true` |
| Campagna                            | Ogni destinatario viene riprovato; diventa `failed` solo dopo tre tentativi     |
| Dashboard, sezione Log              | La richiesta rifiutata, con il corpo della risposta                             |

```json title="400 — POST /api/v1/messages response"
{
  "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"
  }
}
```

Lo status HTTP è `400`, non `429`: decidi se riprovare in base a `meta.retryable`, non allo
status.

## Come risolvo l'errore 130429?

1. **Riprova con un ritardo crescente.** Un singolo invio tramite `POST /api/v1/messages` non viene mai riprovato
   da Genuka WA al posto tuo: una richiesta interattiva non dovrebbe metterci diversi secondi per fallire in silenzio.
   È il tuo codice a riprovare, con un'attesa che raddoppia a ogni tentativo più un po' di jitter, così i tuoi worker
   non ripartono tutti nello stesso millisecondo.
2. **Misura il tuo tetto reale.** `GET /api/v1/numbers` restituisce, per ogni numero, un campo
   `messagesPerSecond` (20, 80 o 1.000) e `coexistence: true` quando il numero è usato anche
   nell'app. Regola il ritmo dei tuoi invii su quel valore, non su un default di 80.
3. **Invia in massa tramite una campagna.** `POST /api/v1/campaigns`, poi
   `/api/v1/campaigns/{id}/launch`: Genuka WA regola l'esecuzione sul throughput del numero e fa fino
   a tre tentativi per destinatario (attese di al massimo 500 ms, poi 1 s, con jitter). Un 130429 isolato
   non ti fa perdere il destinatario. Vedi la
   [guida all'API delle campagne](https://wa.genuka.com/it/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),
    });
    // A 5xx can arrive as plain text (the proxy's "error code: 502"): JSON is not guaranteed.
    const json = await response.json().catch(() => null);
    if (response.ok) return json?.data; // { messageId, warning? }

    // meta.retryable is true for throughput limits (130429, 131056, 4, 80007), Meta internal
    // errors (131000, 5xx), stale media and 131048. That last one is retried later, not in this
    // loop (see the 131048 page). A 5xx with no `meta` does not tell whether the message left:
    // it is thrown as-is, check before resending to avoid a duplicate.
    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:  # a proxy 5xx can arrive as plain text
            body = {}
        if response.ok:
            return body["data"]  # {"messageId": ..., "warning": ...}

        meta = body.get("meta", {})
        # 131048 is retryable, but later: see the 131048 page. A 5xx with no `meta` does not
        # tell whether the message left: it is raised as-is, check before resending.
        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);
        // A proxy 5xx can arrive as plain text: JSON is not guaranteed.
        $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: later (see its page). A 5xx with no "meta" is thrown as-is: check before
        // resending, the message may have left.
        $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
# Each number's throughput, to pace your sends on (stored values).
# To read them again from Meta: ?refresh=true&companyId=..., 25 numbers at most per call.
curl "https://wa.genuka.com/api/v1/numbers" \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY"
# { "data": [ { "id": "con_1", "messagesPerSecond": 80, "coexistence": false, ... } ] }
```

## Come prevengo l'errore 130429?

* **Un solo mittente per numero.** Fai passare ogni invio di un numero da un'unica coda, con un ritmo sotto
  `messagesPerSecond`. È questo che impedisce a due processi di pestarsi i piedi.
* **Pianifica la durata degli invii grandi.** A 20 messaggi/s, un numero in coesistenza invia al massimo
  72.000 messaggi all'ora. Annuncia la durata invece di scoprirla.
* **Usa media ospitati da Meta** per gli invii veloci: Meta consiglia di inviare un ID media invece di un
  URL sui tuoi server per sfruttare un throughput più alto
  ([Meta, Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)).
  Con Genuka WA, `assetId` fa esattamente questo.
* **Non riprovare a intervallo fisso.** Un ciclo "tre tentativi, a un secondo di distanza" invia la stessa raffica
  nello stesso momento e si prende un altro 130429.

## Codici di errore correlati

* [131056](https://wa.genuka.com/it/docs/errors/131056): troppi messaggi verso **lo stesso** destinatario in poco tempo.
* [131048](https://wa.genuka.com/it/docs/errors/131048): invii limitati dopo blocchi o segnalazioni di spam, un problema di
  qualità più che di velocità.
* [4](https://wa.genuka.com/it/docs/errors/4) e [80007](https://wa.genuka.com/it/docs/errors/80007): gli altri due limiti della stessa
  famiglia, che contano le **chiamate API** dell'app e del WhatsApp Business Account, non i messaggi
  inviati.

## FAQ

### Il mio numero può arrivare a 1.000 messaggi al secondo?

Sì, automaticamente e senza costi, quando sono soddisfatte tre condizioni: un limite di messaggistica illimitato,
almeno 100.000 utenti unici contattati fuori da una finestra di servizio in 24 ore mobili, e una
valutazione di qualità almeno media. Durante l'aggiornamento, che richiede fino a un minuto, il numero
risponde `131057` ([Meta, Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)).
Un numero in coesistenza resta a 20 messaggi/s.

### Meta fattura un messaggio rifiutato con 130429?

No. Meta addebita un modello di messaggio solo quando viene consegnato
([Meta, Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)),
e un messaggio rifiutato con 130429 non è mai partito. Lato Genuka WA, un invio rifiutato non
consuma nemmeno la quota del tuo abbonamento: si contano solo i messaggi accettati da Meta.

### Perché Genuka WA risponde 400 e non 429?

Perché ogni rifiuto di Meta su un invio torna come `400`, tranne i problemi di token, permessi e
registrazione del numero, che tornano come `409`. Se riprovare o no si legge in `meta.retryable` e
`meta.errorClass`, che esistono apposta.

### Il 130429 può venire dall'API di Genuka WA stessa?

No. 130429 è un codice Meta che Genuka WA inoltra così com'è in `meta.code`: riguarda sempre il
throughput del numero mittente presso Meta, non la tua chiave API.

## Fonti

* [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)
