# Error 131048 de WhatsApp: envíos restringidos — causa y solución

URL: https://wa.genuka.com/es/docs/errors/131048
Language: Spanish

> Error 131048 de WhatsApp: Meta restringe los envíos del número tras bloqueos o reportes de spam. Cómo leer la calificación de calidad y hacer que vuelva a subir.

El error 131048 de WhatsApp significa que Meta está limitando la cantidad de mensajes que tu
número puede enviar, porque demasiados mensajes anteriores fueron bloqueados o reportados como
spam por sus destinatarios. Es un problema de calidad, no de velocidad. Pausa tus campañas, revisa
la calificación de calidad del número y luego retoma los envíos con destinatarios que dieron su
consentimiento (opt-in).

## ¿Qué significa el error 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, códigos de error de la Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#throttling-errors)

(No se pudo enviar el mensaje porque hay restricciones sobre la cantidad de mensajes que se pueden
enviar desde este número de teléfono. Puede deberse a que demasiados mensajes anteriores fueron
bloqueados o marcados como spam).

Meta remite a tres cosas: el estado de calidad en el Administrador de WhatsApp (en inglés, *WhatsApp Manager*), los límites de mensajes de
plantilla y la calidad de las plantillas. Lo que tienen en común es la **calidad de los mensajes**
tal como la mide Meta
([Meta, Send messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#message-quality)):

* refleja cómo se recibieron tus mensajes **en los últimos siete días**, ponderado según lo
  reciente;
* combina las señales de los usuarios: bloqueos, reportes, silenciamientos, archivados y los
  motivos que dan las personas cuando te bloquean;
* en un número con mucho tráfico, puede cambiar en cuestión de minutos.

La calificación, el estado y el límite de mensajes del número se muestran en el Administrador de WhatsApp, en
**Account tools > Phone numbers**.

## ¿Cuándo aparece el error 131048?

* **Después de una campaña enviada a una lista fría**: contactos importados sin consentimiento,
  clientes antiguos que no esperaban tu mensaje.
* **Cuando una plantilla acumula comentarios negativos**: primero baja su propia calificación,
  luego la del número que la envía.
* **Cuando los mensajes a las mismas personas se suceden con demasiada frecuencia.** Meta incluye
  "enviar demasiados mensajes por día" entre las prácticas que hay que evitar.

### ¿Dónde lo ves en Genuka WA?

| Canal                                                          | Qué recibes                                                                                                                                                                          |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Respuesta de `POST /api/v1/messages`                           | `400`, `"error": "send_retryable"`, `meta.code: 131048`                                                                                                                              |
| Webhook `message_status`, cuando Meta informa el fallo después | `data.status: "failed"`, `data.errors[0].code: 131048`                                                                                                                               |
| Campaña                                                        | Cuando Meta rechaza durante la llamada, cada destinatario afectado se intenta hasta tres veces y luego pasa a `failed`. Si se informa por webhook, pasa a `failed` sin nuevo intento |
| `GET /api/v1/numbers/{id}/health`                              | `qualityRating` (`GREEN`, `YELLOW`, `RED`) leído en vivo desde Meta, más `alerts` cuando cambió                                                                                      |
| Webhook `phone_number_quality_update`                          | El cambio de calidad o de nivel, enviado por Meta                                                                                                                                    |
| `GET /api/v1/templates?sync=true`                              | `qualityScore.score` (`GREEN`, `YELLOW`, `RED`, `UNKNOWN`) de cada plantilla creada con Genuka WA, para encontrar la que causa problemas                                             |

Genuka WA clasifica el 131048 como `retryable`: la restricción termina por levantarse y un intento
posterior puede pasar. Nuestro consejo: aquí `meta.retryable: true` significa "más tarde", no
"ahora". Los tres intentos automáticos de una campaña se suceden en menos de dos segundos y
normalmente también fallan: no lances nada más en este número hasta que su calificación se haya
recuperado.

## ¿Cómo corrijo el error 131048?

1. **Pausa los envíos de marketing del número.** No lances ninguna campaña nueva hasta que la
   calificación se recupere: cada mensaje mal recibido pesa durante los siete días siguientes.
2. **Lee la calificación del número** con `GET /api/v1/numbers/{id}/health`, o en el Administrador de WhatsApp.
3. **Encuentra la plantilla responsable**: `GET /api/v1/templates?sync=true` devuelve
   `qualityScore.score` para cada plantilla creada con Genuka WA; para las creadas en WhatsApp
   Manager, consulta la calificación allí. Detén las que estén en `RED` o `YELLOW` y reescríbelas
   antes de volver a usarlas.
4. **Depura tu audiencia**: conserva los contactos que dieron su consentimiento y que leen tus
   mensajes, descarta los demás y respeta cada baja.
5. **Retoma los envíos de forma gradual**, con envíos pequeños a tus clientes más comprometidos,
   revisando la calificación en cada paso.

**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
// Ejecútalo antes de cada campaña: no empieces con un número que ya está degradado.
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:
    """Ejecútalo antes de cada campaña: no empieces con un número que ya está degradado."""
    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"
```

## ¿Cómo evito el error 131048?

Las pautas de Meta para mensajes de alta calidad
([Meta, Send messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#message-quality)):

* respeta la Política de mensajería de WhatsApp Business;
* escribe solo a personas que dieron su consentimiento (opt-in) para recibir tus mensajes;
* haz que los mensajes sean personalizados y útiles;
* evita los mensajes de bienvenida o de presentación sin un propósito concreto;
* evita enviar demasiados mensajes por día;
* optimiza el contenido y la longitud.

Del lado de la integración, conecta el webhook `phone_number_quality_update` y genera una alerta
en cuanto un número pase a `YELLOW`: ese es el momento de actuar, antes de llegar a `RED`.

## Códigos de error relacionados

* [132015](https://wa.genuka.com/es/docs/errors/132015): una plantilla concreta está pausada por baja calidad.
* [131049](https://wa.genuka.com/es/docs/errors/131049): un destinatario alcanzó su límite de mensajes de marketing; el
  problema no es tu número.
* [130429](https://wa.genuka.com/es/docs/errors/130429): simple exceso de capacidad de envío, sin relación con la
  calidad.

## Preguntas frecuentes

### ¿Cuánto dura una restricción 131048?

Meta no publica ninguna duración. Como la calidad se calcula sobre los últimos siete días, cuenta
con al menos varios días de mensajes bien recibidos antes de que se recupere.

### ¿Puedo evitarlo con otro número de la misma cuenta?

No es una solución: los límites de mensajes se calculan a nivel del portafolio comercial y los
comparten todos sus números
([Meta, Messaging limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)),
y la causa, los mensajes mal recibidos, te seguiría.

### ¿Se ven afectados los mensajes de servicio?

Meta describe una restricción sobre la cantidad de mensajes que el número puede enviar, sin
distinguir categorías. Da prioridad a las respuestas a tus clientes y a los mensajes
transaccionales mientras la calificación se recupera.

## Fuentes

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