Crear cuenta
← Blog

·

Error 131026 en la API de WhatsApp: mensaje no entregado, causas y qué hacer

Actualizado el 29/10/2026

El error 131026 de la API de WhatsApp significa «Unable to deliver message»: Meta aceptó el envío, pero no pudo entregar el mensaje al destinatario. La documentación oficial menciona tres causas posibles: el número no tiene WhatsApp, la persona no aceptó los Términos del Servicio y la Política de Privacidad más recientes, o usa una versión antigua de la aplicación. Reenviar el mismo mensaje no lo resuelve; lo correcto es confirmar el contacto por otro canal y depurar tu base.

Este artículo trata solo el 131026. La tabla general con los demás códigos está en Errores de la API de WhatsApp.

Qué dice Meta sobre el error 131026

En la tabla oficial de códigos de error, el 131026 aparece con la descripción «Unable to deliver message» y tres motivos:

Causa indicada por MetaQué significa en la práctica
El número del destinatario no es un número de WhatsAppNúmero inexistente, mal escrito o que nunca tuvo cuenta de WhatsApp
El destinatario no aceptó los nuevos Términos del Servicio y la Política de PrivacidadLa cuenta existe, pero tiene la aceptación pendiente en la app
El destinatario usa una versión antigua de WhatsAppLa app está por debajo de la versión mínima exigida

Las versiones mínimas que cita la documentación son:

PlataformaVersión mínima
Android y app WhatsApp Business para Android2.21.15.15
iOS y app WhatsApp Business para iOS2.21.170.4
KaiOS2.2130.10
WhatsApp Web2.2132.6

La solución oficial se hace toda fuera de WhatsApp. Meta recomienda pedirle al usuario, por otro canal, que:

  1. confirme que puede enviar un mensaje a tu número comercial;
  2. acepte los términos más recientes, que la app muestra en el menú de configuración (la documentación cita Settings > Help y Settings > Application information);
  3. actualice WhatsApp a la versión más reciente.

Un punto clave: la API no informa cuál de las tres causas ocurrió. El código es el mismo para todas.

¿Y el bloqueo? Dónde entra

Muchas listas en internet dicen que el 131026 significa «el usuario bloqueó a la empresa». La tabla de errores no dice eso. El bloqueo aparece en otra página, la de soporte de la Cloud API, en la sección sobre mensajes que quedan como enviados pero no se entregan. Ahí Meta enumera:

  • el usuario no se conectó durante los 30 días en que Meta guarda los mensajes para quien está desconectado;
  • el cliente bloqueó el número comercial, u otro número comercial de la misma empresa;
  • el cliente está en un país restringido o sancionado.

La misma página advierte que, en muchos de estos casos, Meta no revela la causa. Por eso, trata el bloqueo como una hipótesis de «enviado sin entrega», no como un significado del 131026. La página también menciona casos en que la API sí devuelve un código de error, como términos no aceptados y versión desactualizada, que son justamente dos de las causas del 131026.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Dónde aparece el 131026

El 131026 llega de forma asíncrona, en el webhook messages, como un estado failed con el arreglo errors. La respuesta de la llamada de envío puede haber sido exitosa, con un wamid; la falla llega después. Un ejemplo del evento:

{
  "statuses": [
    {
      "id": "wamid.HBgLNTU4NDk5OTk5OTk5...",
      "status": "failed",
      "timestamp": "1761750000",
      "recipient_id": "5584999999999",
      "errors": [
        {
          "code": 131026,
          "title": "Unable to deliver message.",
          "message": "Unable to deliver message.",
          "error_data": {
            "details": "Unable to deliver message."
          }
        }
      ]
    }
  ]
}

Los textos de title y details pueden variar. Arma la lógica sobre el code. El ciclo completo de estados (sent, delivered, read, failed) está explicado en estado de mensaje por webhook, y el diagnóstico de mensajes que se quedan en sent está en mensaje enviado pero no entregado.

Cómo distinguir las causas

La API no las distingue, pero tu historial ayuda. Algunas pistas prácticas, que son inferencias a partir de tus propios datos y no una regla de Meta:

Lo que sabe tu sistemaCausa más probableQué hacer
El contacto nunca te escribió y el número vino de un formulario escrito a manoNúmero sin WhatsApp o mal escritoConfirmar el número por correo o SMS; corregir el registro
El contacto ya conversó contigo por WhatsAppTérminos pendientes o app desactualizadaAvisar por otro canal para que actualice la app y acepte los términos
Otros mensajes al mismo contacto se entregaron ayerSituación temporal del lado del usuarioPausar los envíos a ese contacto e intentar una vez más después
El número tiene un formato raro (sin código de país, dígitos de más)Error de registroNormalizar al formato internacional, solo dígitos, con código de país

Si el contacto ya conversó con tu empresa, el número tuvo WhatsApp en algún momento. Eso hace menos probable la primera causa y apunta a términos o versión de la app.

Cuándo no reenviar

La regla general: no reenvíes en bucle. El 131026 no es un error temporal de infraestructura, como el 131000 o el 130429. Depende de algo que solo el usuario puede resolver (tener WhatsApp, aceptar términos, actualizar la app).

  • No pongas el 131026 en la cola de reintentos con espera exponencial.
  • No envíes la misma plantilla otra vez el mismo día.
  • No cambies de plantilla pensando que el contenido es el problema. Este código no tiene que ver con el contenido.
  • Puedes intentar una vez más después (días después) si hay señal de que el usuario lo resolvió, por ejemplo, cuando confirmó por correo que actualizó la app.
  • Puedes volver a enviar con normalidad cuando el contacto te escriba, porque eso prueba que su WhatsApp funciona.

Costo: ¿se cobra un mensaje con error 131026?

No. La página de precios de Meta dice que la empresa solo paga cuando el mensaje se entrega. Un mensaje que termina en failed con 131026 no se entregó.

El costo real es otro: tiempo del equipo, campañas con menos alcance del planeado y una base cada vez más sucia. En Brasil, por ejemplo, un mensaje de marketing cuesta R$ 0,3217 (reales) por mensaje entregado desde el 1/10/2026. Los números que fallan no suman a la factura, pero distorsionan el pronóstico si calculas el costo por el tamaño de la lista.

Respaldo: SMS y correo electrónico

Como la propia Meta indica resolverlo por un canal fuera de WhatsApp, conviene tener un respaldo automático para los mensajes importantes:

  • Transaccional (pedido, pago, código): si el estado es failed con 131026, envía el mismo aviso por SMS o correo. Para códigos de verificación, un respaldo por SMS evita que el usuario quede trabado en el inicio de sesión. Comparamos ambos canales en WhatsApp o SMS.
  • Marketing: no fuerces otro canal solo porque WhatsApp falló. Usa el correo solo si la persona también autorizó ese canal.
  • Mensaje de reactivación: un correo breve que pida confirmar el número, actualizar WhatsApp, aceptar los términos y mandar un «hola» a tu número cubre de una vez las tres indicaciones de Meta. Si el «hola» llega, además abre la ventana de atención.

Limpieza de base

El 131026 es un buen termómetro de la calidad de tu lista. Una rutina sencilla:

  1. Registra cada 131026 con contacto, fecha y plantilla.
  2. Tras fallas repetidas en fechas distintas, marca el contacto como whatsapp_no_disponible y sácalo de las campañas.
  3. Pide la actualización del número por correo o en la próxima interacción en tu sitio o app.
  4. Reactiva el contacto automáticamente si te escribe.
  5. Sigue la tasa de 131026 por origen del lead (formulario, importación, tienda física). Un origen con tasa alta indica un problema de captura.

El artículo sobre cómo armar una lista opt-in para WhatsApp muestra cómo capturar el número con confirmación, lo que reduce el primer tipo de falla.

Ejemplo de código: clasificar y marcar el contacto

El fragmento siguiente procesa el estado del webhook, aísla el 131026 y decide entre respaldo y marcar el contacto. El límite de fallas lo eliges tú, no Meta.

const LIMITE_FALLAS = 3; // fallas 131026 en días distintos antes de suspender

async function onStatus(status, db, respaldo) {
  if (status.status !== 'failed') return;
  const err = (status.errors || []).find(e => e.code === 131026);
  if (!err) return;

  const contacto = await db.contactos.findByWaId(status.recipient_id);
  const msg = await db.mensajes.findByWamid(status.id);

  await db.fallas.insert({
    wa_id: status.recipient_id,
    wamid: status.id,
    code: err.code,
    details: err.error_data?.details,
    dia: new Date(Number(status.timestamp) * 1000).toISOString().slice(0, 10)
  });

  // Mensaje transaccional: avisar por otro canal
  if (msg?.tipo === 'transaccional' && contacto?.email) {
    await respaldo.email(contacto.email, msg.resumen);
  }

  // Sin conversación previa y fallas repetidas: suspender el contacto
  const dias = await db.fallas.distinctDias(status.recipient_id, 131026);
  if (!contacto?.ultimo_mensaje_recibido && dias.length >= LIMITE_FALLAS) {
    await db.contactos.update(status.recipient_id, { whatsapp_no_disponible: true });
  }
}

Cuando llegue un mensaje de ese contacto (messages en el webhook), borra la marca: su WhatsApp volvió a funcionar.

Cómo hacerlo con Vectalk

Vectalk es un proxy de la Cloud API oficial de Meta, así que el 131026 llega igual: estado failed en el webhook, con el mismo arreglo errors de la documentación de Meta. El código de arriba funciona sin cambios. Para revisar las fallas de un período, usa GET https://apis.vectalk.com.br/api/messages?status=failed&from=2026-10-01, descrito en Listar Mensajes.

En Vectalk, cada mensaje entregado se descuenta del saldo prepago, y Vectalk le paga a Meta. Un mensaje que falla con 131026 no se entregó. Crea tu cuenta en apps.vectalk.com.br/register y consulta el panorama en la guía de la API oficial de WhatsApp.

Preguntas frecuentes

¿El error 131026 significa que el número no tiene WhatsApp?

Puede significarlo, pero no solo eso. Meta indica tres causas: número sin WhatsApp, términos y política de privacidad no aceptados, y versión antigua de la app. El código es el mismo para las tres.

¿El error 131026 quiere decir que el cliente me bloqueó?

La tabla de errores no menciona el bloqueo como causa del 131026. El bloqueo aparece en la página de soporte de Meta entre los motivos por los que un mensaje queda como enviado sin entregarse, y Meta advierte que muchas veces no revela la causa.

¿Me cobran los mensajes con error 131026?

No. Meta solo cobra los mensajes entregados, y un mensaje con estado failed no se entregó.

¿Cuántas veces debo reenviar?

Ninguna de inmediato. Pide al contacto, por otro canal, que confirme el número, actualice la app y acepte los términos. Vuelve a enviar cuando lo confirme o te escriba.

¿Puedo evitar el 131026 antes de enviar?

Se puede reducir. Captura el número con confirmación, normaliza al formato internacional y prioriza contactos que ya conversaron contigo. Para quien nunca habló con la empresa, no hay forma de garantizar la entrega antes del envío.

Fuentes oficiales consultadas el 29/10/2026: Códigos de error de la WhatsApp Cloud API, Soporte de la WhatsApp Cloud API, Referencia del webhook de estado, Precios de la plataforma de WhatsApp Business, Listar Mensajes en la documentación de Vectalk.

Prueba hoy la API oficial de WhatsApp

Crea tu cuenta, genera el token y envía el primer mensaje con la guía de la documentación. Los mismos payloads y webhooks de la Cloud API de Meta.

Crear cuenta gratis
Leer la documentación