Errores de la API de WhatsApp: qué significa cada uno y cómo manejarlos

"Error al enviar el mensaje." Es lo que registra la mayoría de los logs, y es inútil: no dice si hay que reintentar, avisarle a alguien o desistir.

Este artículo separa los errores que de verdad vas a encontrar y el manejo correcto de cada uno.

Primero: 200 no es entrega

const r = await enviar(to, texto);   // 200 OK
// esto NO quiere decir que el mensaje llegó

El 200 significa que la plataforma aceptó el mensaje. La entrega se confirma después, por el webhook de estado — en value.statuses, como delivered o failed.

Quien solo mira la respuesta de la llamada nunca se entera de los fallos de entrega. Por eso medir con el webhook de estado no es opcional.

La división que ordena todo

Reintentar un error definitivo es el desperdicio más común en una cola de envío: gasta cuota, atrasa a quien viene detrás y nunca funciona.

Los errores, uno por uno

Ventana de 24 horas cerrada

El más común de todos entre quienes empiezan con notificaciones.

Intentaste mandar texto libre a alguien que no escribe hace más de 24 horas. En la API oficial, eso no sale.

if (e.code === 'fuera_de_ventana') {
  // No reintentes: en 5 minutos dará el mismo error.
  // Reenvía como plantilla aprobada.
  return enviarPlantilla(to, 'aviso_generico', params);
}

El manejo no es un reintento — es usar una plantilla. Si tu flujo manda notificaciones, siempre se va a encontrar con la ventana cerrada, porque el mensaje sale de ti.

Número inválido o sin WhatsApp

Definitivo. Marca y sigue:

if (e.code === 'sin_whatsapp' || e.code === 'numero_invalido') {
  await db.contactos.marcar(to, 'invalido');
  return;   // nunca más intentes con este número
}

Prevenir es mejor: verifica la base antes de la campaña. En la API oficial, un intento fallido repetido perjudica la reputación del número. El procedimiento está en limpieza de la lista.

Plantilla no aprobada o pausada

Definitivo, y necesita intervención humana:

if (e.code === 'plantilla_no_aprobada') {
  await alertarEquipo(`Plantilla ${nombre} no disponible — campaña pausada`);
  await pausarCampana(campanaId);
  return;
}

Pausa la campaña entera, no solo el mensaje. Si la plantilla se cayó, los próximos 5.000 envíos van a fallar igual — y cada intento empeora el cuadro.

Una plantilla aprobada puede quedar pausada después, si recibe muchos bloqueos. La aprobación no es permanente.

Límite alcanzado

Temporal, y el manejo equivocado lo empeora:

if (e.status === 429) {
  const espera = Number(e.headers?.['retry-after'] ?? 60) * 1000;
  throw new ErrorTemporal(espera);   // la cola se encarga del backoff
}

Respeta el Retry-After cuando venga. Sin él, backoff exponencial con jitter — reintentar todo junto en el mismo instante recrea el mismo límite. El diseño completo está en cola, rate limit y reintentos.

Instancia desconectada

Temporal, pero no sirve reintentar en 2 segundos: alguien tiene que reconectar.

if (e.code === 'instancia_desconectada') {
  await alertarEquipo(`La instancia de ${cliente.nombre} se cayó`);
  await notificarCliente(cliente, 'canal_desconectado');
  throw new ErrorTemporal(15 * 60 * 1000);   // reintenta en 15 min
}

Avisarle al cliente antes de que lo note cambia la conversación: de "tu sistema está roto" a "vimos que se cayó y ya lo estamos resolviendo".

Esto pesa más en la API no oficial, donde la sesión puede caerse sola. La conexión sin celular elimina la causa más común, que es el teléfono.

Archivo rechazado

Definitivo, y casi siempre por la URL:

if (e.code === 'archivo_invalido') {
  // Causas: URL no pública, sin HTTPS, archivo demasiado grande,
  // formato no soportado, o el servidor devolviendo HTML en vez del archivo.
  await db.envios.marcar(id, 'archivo_invalido');
  return;
}

El caso más traicionero es la URL que exige autenticación: en tu navegador abre porque tienes sesión, y para la plataforma devuelve la página de login. Pruébala siempre en una ventana de incógnito.

El contacto te bloqueó

Definitivo, y es información valiosa:

if (e.code === 'contacto_bloqueo') {
  await db.contactos.marcar(to, 'bloqueo');
  await registrarEnMetrica(campanaId, 'bloqueo');
  return;
}

No lo trates como un fallo técnico. El bloqueo es señal de contenido, y es el indicador que avisa antes de que el número se queme.

El handler que lo une todo

const DEFINITIVOS = new Set([
  'sin_whatsapp', 'numero_invalido', 'plantilla_no_aprobada',
  'contacto_bloqueo', 'archivo_invalido', 'fuera_de_ventana',
]);

async function enviarConManejo(job) {
  const { to, payload, campanaId } = job.data;

  try {
    const r = await api.enviar(to, payload);
    await db.envios.exito(campanaId, to, r.messageId);
  } catch (e) {
    const definitivo = DEFINITIVOS.has(e.code) ||
                       (e.status >= 400 && e.status < 500 && e.status !== 429);

    // Log con lo que permite actuar: código, destinatario, intento.
    // "error al enviar" no permite nada.
    console.error({
      evento: 'fallo_envio',
      campana: campanaId,
      to,
      code: e.code,
      status: e.status,
      intento: job.attemptsMade + 1,
      definitivo,
    });

    if (definitivo) {
      await db.envios.fallo(campanaId, to, e.code);
      return;   // no reintenta
    }
    throw e;    // reintenta con backoff
  }
}

Qué registrar

Un log que sirve tiene código, destinatario y número de intento. Con eso respondes las tres preguntas que aparecen cuando algo sale mal:

• ¿Qué error está creciendo hoy?
• ¿Este número falla siempre o fue una vez?
• ¿Estamos reintentando algo que nunca va a funcionar?

Una alerta simple cierra el ciclo: si la tasa de fallo de una campaña pasa del 10%, detente y avisa. Una campaña que falla en masa con la plantilla pausada consume cuota y empeora la reputación en cada intento.

Conclusión

El manejo de errores en una API de mensajería es una sola decisión, repetida: ¿esto cambia si lo intento de nuevo?

Si cambia, es cola y backoff. Si no cambia, es registro con motivo y seguir adelante. Equivocar esa clasificación es lo que hace que una cola se trabe durante horas repitiendo "el número no existe" — o que se rinda con mensajes que habrían salido en el segundo intento.