# Errore WhatsApp 131048: invii limitati — causa e soluzione

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

> Errore WhatsApp 131048: Meta limita gli invii del numero dopo blocchi o segnalazioni di spam. Come leggere la valutazione di qualità e farla risalire.

L'errore WhatsApp 131048 significa che Meta sta limitando quanti messaggi il tuo numero può inviare, perché troppi
messaggi precedenti sono stati bloccati o segnalati come spam dai destinatari. È un problema di
qualità, non di velocità. Metti in pausa le tue campagne, controlla la valutazione di qualità del numero, poi riprendi
con destinatari che hanno dato il consenso.

## Cosa significa l'errore 131048?

> "Message failed to send because there are restrictions on how many messages can be sent from
> this phone number. This may be because too many previous messages were blocked or flagged as
> spam."
> — [Meta, Cloud API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#throttling-errors)

Meta indica tre cose: lo stato di qualità in WhatsApp Manager, i limiti di messaggistica dei modelli
e la qualità dei modelli. Ciò che le accomuna è la **qualità dei messaggi** come la misura Meta
([Meta, Send messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#message-quality)):

* riflette come sono stati accolti i tuoi messaggi **negli ultimi sette giorni**, con più peso a quelli recenti;
* combina i segnali di feedback degli utenti: blocchi, segnalazioni, silenziamenti, archiviazioni e i motivi che le persone indicano
  quando ti bloccano;
* su un numero con molto traffico, può cambiare nel giro di minuti.

La valutazione, lo stato e il limite di messaggistica del numero sono visibili in WhatsApp Manager sotto **Account
tools > Phone numbers**.

## Quando si verifica l'errore 131048?

* **Dopo una campagna inviata a una lista fredda**: contatti importati senza consenso, vecchi clienti che
  non si aspettavano un tuo messaggio.
* **Quando un modello continua a raccogliere feedback negativi**: cala prima la sua valutazione, poi quella
  del numero che lo invia.
* **Quando i messaggi si susseguono troppo spesso** verso le stesse persone. Meta elenca "sending too many
  messages per day" tra le pratiche da evitare.

### Dove lo vedi in Genuka WA?

| Canale                                                                 | Cosa ottieni                                                                                                                                                                              |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Risposta di `POST /api/v1/messages`                                    | `400`, `"error": "send_retryable"`, `meta.code: 131048`                                                                                                                                   |
| Webhook `message_status`, quando Meta segnala il fallimento in seguito | `data.status: "failed"`, `data.errors[0].code: 131048`                                                                                                                                    |
| Campagna                                                               | Quando Meta rifiuta già alla chiamata, ogni destinatario coinvolto viene tentato fino a tre volte, poi diventa `failed`. Se segnalato via webhook, diventa `failed` senza nuovi tentativi |
| `GET /api/v1/numbers/{id}/health`                                      | `qualityRating` (`GREEN`, `YELLOW`, `RED`) letto in tempo reale da Meta, più `alerts` quando è cambiato                                                                                   |
| Webhook `phone_number_quality_update`                                  | Il cambio di qualità o di livello, inviato da Meta                                                                                                                                        |
| `GET /api/v1/templates?sync=true`                                      | `qualityScore.score` (`GREEN`, `YELLOW`, `RED`, `UNKNOWN`) per ogni modello creato tramite Genuka WA, per trovare quello che crea problemi                                                |

Genuka WA classifica 131048 come `retryable`: la restrizione prima o poi si toglie, e un tentativo successivo
può andare a buon fine. Il nostro consiglio: qui `meta.retryable: true` significa "più tardi", non "adesso". I
tre tentativi automatici di una campagna si susseguono in meno di due secondi e di solito falliscono anch'essi: non lanciare
più nulla su questo numero finché la sua valutazione non si è ripresa.

## Come risolvo l'errore 131048?

1. **Metti in pausa gli invii di marketing del numero.** Non lanciare nuove campagne finché la valutazione non si riprende: ogni
   messaggio accolto male pesa sui sette giorni successivi.
2. **Leggi la valutazione del numero** con `GET /api/v1/numbers/{id}/health`, oppure in WhatsApp Manager.
3. **Trova il modello responsabile**: `GET /api/v1/templates?sync=true` restituisce `qualityScore.score` per
   ogni modello creato tramite Genuka WA; per quelli creati in WhatsApp Manager, leggi la valutazione
   lì. Ferma quelli a `RED` o `YELLOW`, e riscrivili prima di usarli di nuovo.
4. **Pulisci il tuo pubblico**: tieni i contatti che hanno dato il consenso e che leggono, togli gli altri, e rispetta
   ogni disiscrizione.
5. **Riprendi gradualmente**, con piccoli invii ai tuoi clienti più coinvolti, controllando la valutazione a
   ogni passo.

**curl**

```bash
curl https://wa.genuka.com/api/v1/numbers/con_1/health \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY"
# {
#   "data": { "connectionId": "con_1", "qualityRating": "YELLOW", "messagesPerSecond": 80, ... },
#   "alerts": [ { "kind": "quality_dropped", "severity": "warning", "from": "GREEN", "to": "YELLOW", "message": "..." } ]
# }
```

**Node.js**

```ts
// Run before every campaign: do not start on a number that is already degraded.
export async function canLaunchCampaign(connectionId: string): Promise<boolean> {
  const response = await fetch(`https://wa.genuka.com/api/v1/numbers/${connectionId}/health`, {
    headers: { Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}` },
  });
  const { data } = await response.json();
  return data.qualityRating === "GREEN";
}
```

**Python**

```python
import os
import requests


def can_launch_campaign(connection_id: str) -> bool:
    """Run before every campaign: do not start on a number that is already degraded."""
    response = requests.get(
        f"https://wa.genuka.com/api/v1/numbers/{connection_id}/health",
        headers={
            "Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}",
            "User-Agent": "acme-crm/1.0 (+https://example.com)",
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["data"]["qualityRating"] == "GREEN"
```

## Come prevengo l'errore 131048?

Le linee guida di Meta per messaggi di alta qualità
([Meta, Send messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#message-quality)):

* rispetta la WhatsApp Business Messaging Policy;
* scrivi solo a persone che hanno acconsentito a ricevere i tuoi messaggi;
* rendi i messaggi personalizzati e utili;
* evita messaggi di benvenuto o di presentazione generici;
* evita di inviare troppi messaggi al giorno;
* ottimizza contenuto e lunghezza.

Lato integrazione, collega il webhook `phone_number_quality_update` e lancia un allarme appena un
numero passa a `YELLOW`: è il momento di agire, prima di `RED`.

## Codici di errore correlati

* [132015](https://wa.genuka.com/it/docs/errors/132015): un modello specifico è in pausa per bassa qualità.
* [131049](https://wa.genuka.com/it/docs/errors/131049): un destinatario ha raggiunto il suo limite di messaggi di marketing; il tuo
  numero non c'entra.
* [130429](https://wa.genuka.com/it/docs/errors/130429): semplice superamento del throughput, senza legame con la qualità.

## FAQ

### Quanto dura una restrizione 131048?

Meta non pubblica alcuna durata. Visto che la qualità è calcolata sugli ultimi sette giorni, metti in conto almeno
diversi giorni di messaggi ben accolti prima che si riprenda.

### Posso aggirarla con un altro numero sullo stesso account?

Non è una soluzione: i limiti di messaggistica sono calcolati a livello di portafoglio business e condivisi da tutti
i suoi numeri
([Meta, Messaging limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)),
e la causa, cioè i messaggi accolti male, ti seguirebbe.

### I messaggi di servizio sono coinvolti?

Meta descrive una restrizione su quanti messaggi il numero può inviare, senza distinguere tra
categorie. Dai la priorità alle risposte ai tuoi clienti e ai messaggi transazionali mentre la valutazione
si riprende.

## Fonti

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Send messages, message quality](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#message-quality)
* [Meta — Template quality rating](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-quality)
* [Meta — Messaging limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)
