Errore WhatsApp 4: limite di frequenza dell'app raggiunto — soluzione
Errore WhatsApp 4 (API Too Many Calls): l'app ha raggiunto il suo limite di frequenza delle chiamate all'API di Meta. In cosa si distingue da 80007 e 130429, e come riprovare in sicurezza.
L'errore WhatsApp 4 significa che l'applicazione che chiama l'API di Meta ha raggiunto il suo limite di frequenza delle chiamate. È una limitazione temporanea: non c'è nulla di rotto, devi aspettare e inviare meno richieste. Si applica all'applicazione nel suo insieme, non a un numero o a un account WhatsApp, ed è questo che lo distingue dagli errori 80007 e 130429.
Cosa significa l'errore 4?
Meta lo elenca tra gli errori di limitazione della Cloud API:
"The app has reached its API call rate limit." — Meta, Cloud API error codes
La soluzione suggerita: apri l'app nella App Dashboard, sezione Application Rate Limit, verifica che il limite sia stato raggiunto, poi riprova più tardi oppure riduci la frequenza e il numero di richieste. La documentazione della Graph API chiama questo codice "API Too Many Calls", un problema di limitazione temporaneo: "Wait and retry the operation, or examine your API request volume" (Meta, Graph API error handling). La sua pagina sui limiti di frequenza aggiunge che il codice 4 indica che l'app il cui token è usato nella richiesta ha raggiunto il suo limite (Meta, Rate limits).
Quattro limiti, quattro codici
| Codice | Cosa viene contato | Ambito |
|---|---|---|
| 4 | Le chiamate API dell'applicazione | L'intera applicazione |
| 80007 | Le chiamate di un'app su un account WhatsApp: 200 all'ora per impostazione predefinita, 5.000 su un account attivo con un numero registrato | Un'app e un account WhatsApp |
| 130429 | Messaggi al secondo: 80 per impostazione predefinita | Un numero |
| 131056 | Messaggi allo stesso destinatario: uno ogni 6 secondi | Una coppia mittente e destinatario |
Le cifre provengono dalla panoramica della piattaforma di Meta (Meta, About the platform).
Quando si verifica l'errore 4?
- Una raffica di chiamate che non sono invii: elencare i modelli in un ciclo, rileggere la salute di ogni numero a ogni caricamento della dashboard, caricare media uno dopo l'altro.
- Più servizi sulla stessa app: un worker delle campagne, un back office e uno script di sincronizzazione che condividono un token sommano le loro chiamate.
- Un ciclo di nuovi tentativi senza attesa: ogni fallimento scatena subito un'altra chiamata, e il limite si allontana invece di avvicinarsi.
Dove lo vedi in Genuka WA?
Con Genuka WA, l'applicazione Meta che fa la chiamata è quella di Genuka, in qualità di Tech
Provider: il limite dell'applicazione non dipende solo dal tuo volume. Genuka colloca il codice 4
nella classe retryable.
| Canale | Cosa ricevi |
|---|---|
POST /api/v1/messages | 400, "error": "send_retryable", meta.code: 4, meta.retryable: true |
| Campagna | Ogni destinatario ha fino a tre tentativi in totale (due nuovi tentativi), con attese da 0.25 a 0,5 s e poi da 0.5 a 1 s, prima di passare a failed |
POST /api/v1/templates | 422, "error": "meta_rejected", meta.retryable: true se Meta ha risposto con un 4xx; 502 se ha risposto 429 o 5xx |
Quel 502 arriva senza corpo JSON: la nostra CDN sostituisce la risposta con la sola riga
error code: 502 (riferimento API). Trattalo come un errore temporaneo, senza
cercarci dentro meta.
Genuka limita anche le raffiche che potrebbe causare per conto tuo: GET /api/v1/numbers?refresh=true
rifiuta la chiamata (400 too_many_connections) oltre i 25 numeri, quindi restringila con
?companyId=; e un aggiornamento dei modelli elabora gli account WhatsApp cinque alla volta.
Come risolvo l'errore 4?
Riprova con un'attesa crescente, solo quando meta.retryable è true o su un 5xx senza corpo
JSON. Un singolo invio non viene riprovato da Genuka WA per conto tuo: è il tuo codice che deve
aspettare, raddoppiando l'attesa a ogni tentativo e aggiungendo un po' di casualità, così che i tuoi
worker non ripartano tutti insieme.
Per un invio, riprova solo quando meta.code è presente (4, 80007, 130429…). Anche un timeout tra
Genuka e Meta è segnato come retryable, senza meta.code, sebbene Meta possa aver già accettato
il messaggio; l'API non ha chiave di idempotenza, e inviarlo di nuovo può consegnarlo due volte.
Elimina le chiamate di lettura superflue. GET /api/v1/numbers senza refresh=true restituisce
lo stato memorizzato, tenuto aggiornato dai webhook di Meta. Gli stati dei modelli arrivano via
webhook; l'aggiornamento POST /api/v1/templates/sync è un percorso di
riparazione, e una volta all'ora è più che sufficiente (riferimento API).
Se l'errore dura più di un'ora, contatta il supporto Genuka con l'header x-request-id e il
meta.traceId: i limiti della Graph API sono calcolati su un'ora mobile.
Se chiami la Cloud API con la tua app, la App Dashboard mostra l'utilizzo attuale dell'Application Rate Limit dell'app e il numero di utenti limitati (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 arriva senza JSON: la nostra CDN lo sostituisce con "error code: 502".
const json = await response.json().catch(() => null);
if (response.ok) return json.data;
// Un invio si riprova solo su un codice di Meta (4, 80007, 130429…): dopo un timeout, Meta potrebbe
// aver già accettato il messaggio, e inviarlo di nuovo lo consegnerebbe due volte.
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 ?? "nessun corpo JSON"} (Meta ${json?.meta?.code ?? "-"})`);
}
const base = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
await sleep(base / 2 + Math.random() * (base / 2));
}
}Come prevengo l'errore 4?
- Preferisci i webhook al polling. Gli stati dei messaggi, le revisioni dei modelli e i cambiamenti di qualità arrivano da soli; chiederli in un ciclo consuma il limite per niente.
- Invia in massa tramite una campagna. Genuka regola il ritmo dell'invio sul throughput del numero e gestisce i nuovi tentativi destinatario per destinatario — vedi le campagne tramite API.
- Non riprovare mai a intervallo fisso. Tre tentativi a un secondo di distanza ripetono la stessa raffica nello stesso momento.
Codici di errore correlati
- 80007: il limite di chiamate di un'app su un account WhatsApp.
- 130429: il throughput di messaggi al secondo di un numero.
- 131056: troppi messaggi allo stesso destinatario in poco tempo.
FAQ
L'errore 4 viene dalla mia chiave API Genuka?
No. È un codice di Meta, riportato in meta.code. Riguarda l'applicazione Meta che fa la chiamata,
quella di Genuka, non la tua chiave.
Quanto devo aspettare?
Meta non indica una durata fissa per il codice 4: i limiti della Graph API sono calcolati su un'ora mobile. Comincia con un'attesa crescente, da uno a trenta secondi, e riduci le tue chiamate; se l'errore dura più di un'ora, avvisa il supporto.
Un messaggio rifiutato con il codice 4 viene fatturato?
Meta non l'ha accettato, quindi non c'è nessun messaggio da fatturare. Dal lato di Genuka WA, contano sulla quota del tuo piano solo i messaggi accettati da Meta.
Fonti
Errore WhatsApp 200: accesso negato (200-299) — soluzione
Errore 200 della WhatsApp Cloud API: token mancante, autorizzazione revocata o un utente di sistema senza accesso all'account. Come diagnosticarlo e risolverlo.
Errore WhatsApp 80007: limite di frequenza dell'account raggiunto — soluzione
Errore WhatsApp 80007: il WhatsApp Business Account ha raggiunto il suo limite di chiamate API (200 o 5.000 all'ora). Quali chiamate contano, e come evitarlo.