# Errore WhatsApp 4: limite di frequenza dell'app raggiunto — soluzione

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

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#throttling-errors)

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](https://developers.facebook.com/docs/graph-api/guides/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](https://developers.facebook.com/docs/graph-api/overview/rate-limiting)).

### Quattro limiti, quattro codici

| Codice                           | Cosa viene contato                                                                                                                          | Ambito                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| **4**                            | Le chiamate API dell'applicazione                                                                                                           | L'intera applicazione              |
| [80007](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/130429) | Messaggi al secondo: 80 per impostazione predefinita                                                                                        | Un numero                          |
| [131056](https://wa.genuka.com/it/docs/errors/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#rate-limits)).

## 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](https://wa.genuka.com/it/docs/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?

1. **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.

2. **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](https://wa.genuka.com/it/docs/webhooks); l'aggiornamento `POST /api/v1/templates/sync` è un percorso di
   riparazione, e una volta all'ora è più che sufficiente ([riferimento API](https://wa.genuka.com/it/docs/api#modelli)).

3. **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](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 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));
  }
}
```

**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 arriva senza JSON: la nostra CDN lo sostituisce con "error code: 502".
            payload = {}
        if response.ok:
            return payload["data"]
        meta = payload.get("meta") or {}
        # 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.
        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', 'nessun corpo 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 quando la richiesta non si è mai conclusa
        curl_close($ch);
        // Un 5xx arriva senza JSON: la nostra CDN lo sostituisce con "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 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.
        $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"] ?? "nessun corpo 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 tentativo: leggi meta.retryable prima di decidere se riprovare.
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": "Il tuo pacco è in viaggio." }' \
  | jq '{error, code: .meta.code, retryable: .meta.retryable}'
```

## 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](https://wa.genuka.com/it/docs/guides/campaigns-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](https://wa.genuka.com/it/docs/errors/80007): il limite di chiamate di un'app su un account WhatsApp.
* [130429](https://wa.genuka.com/it/docs/errors/130429): il throughput di messaggi al secondo di un numero.
* [131056](https://wa.genuka.com/it/docs/errors/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

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