Genuka WA docs

Errore WhatsApp 130429: Rate limit hit — causa e soluzione

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

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

NumeroThroughput massimo
Numero Cloud API standard80 messaggi/s
Numero aggiornato automaticamente da Metafino 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:

TettoCosa contaCodice
ThroughputMessaggi al secondo, per numero130429
Limite di frequenza per coppiaMessaggi verso lo stesso destinatario131056
Limite di messaggisticaDestinatari unici fuori dalla finestra di servizio su 24 h mobili, a livello di portafoglio businessvedi Meta, Messaging limits

Dove lo vedi in Genuka WA?

CanaleCosa ottieni
Risposta di POST /api/v1/messages400, "error": "send_retryable", meta.code: 130429, meta.retryable: true
CampagnaOgni destinatario viene riprovato; diventa failed solo dopo tre tentativi
Dashboard, sezione LogLa richiesta rifiutata, con il corpo della risposta
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?

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.

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.

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.

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

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). 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: troppi messaggi verso lo stesso destinatario in poco tempo.
  • 131048: invii limitati dopo blocchi o segnalazioni di spam, un problema di qualità più che di velocità.
  • 4 e 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). 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), 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

In questa pagina