Genuka WA docs

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

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

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

  • 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?

CanalQué recibes
Respuesta de POST /api/v1/messages400, "error": "send_retryable", meta.code: 131048
Webhook message_status, cuando Meta informa el fallo despuésdata.status: "failed", data.errors[0].code: 131048
CampañaCuando 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}/healthqualityRating (GREEN, YELLOW, RED) leído en vivo desde Meta, más alerts cuando cambió
Webhook phone_number_quality_updateEl cambio de calidad o de nivel, enviado por Meta
GET /api/v1/templates?sync=truequalityScore.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?

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.

Lee la calificación del número con GET /api/v1/numbers/{id}/health, o en el Administrador de WhatsApp.

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.

Depura tu audiencia: conserva los contactos que dieron su consentimiento y que leen tus mensajes, descarta los demás y respeta cada baja.

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 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": "..." } ]
# }

¿Cómo evito el error 131048?

Las pautas de Meta para mensajes de alta calidad (Meta, Send messages):

  • 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: una plantilla concreta está pausada por baja calidad.
  • 131049: un destinatario alcanzó su límite de mensajes de marketing; el problema no es tu número.
  • 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), 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

En esta página