​

Códigos de Error

​

Estructura de Error

{
  "error": "message_delivery_failed",
  "message": "Descripción legible del error",
  "code": "131047",
  "action_required": "Acción sugerida",
  "instructions": "Pasos detallados para resolver",
  "data": {
    "id": "uuid-del-mensaje",
    "status": "failed"
  }
}

​

Errores HTTP de Whaapy

​

Errores de WhatsApp (Meta)

​

131047 - Ventana de 24 Horas Expirada

1. Envía un template message pre-aprobado por Meta
2. Espera a que el usuario te escriba primero
3. Usa el endpoint /retry después de que se reabra la ventana

{
  "error": "message_delivery_failed",
  "message": "La ventana de conversación de 24 horas ha expirado",
  "code": "131047",
  "action_required": "Usar template message",
  "instructions": "Para contactar usuarios después de 24h sin respuesta, debes enviar un template aprobado por Meta",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed"
  }
}

​

131042 - Pago Requerido

1. Ve a Meta Business Suite
2. Navega a Configuración → Pagos
3. Agrega o actualiza tu método de pago
4. Verifica que no haya pagos rechazados

{
  "error": "message_delivery_failed",
  "message": "Se requiere configurar método de pago",
  "code": "131042",
  "action_required": "Configurar pago en Meta Business",
  "instructions": "Ve a Meta Business Suite > Configuración > Pagos y agrega un método de pago válido"
}

​

130472 - Número Inválido

1. Verifica que el número incluya código de país (ej: +521 para México)
2. Confirma que el usuario tiene WhatsApp instalado
3. El número puede haber sido dado de baja de WhatsApp

{
  "error": "invalid_recipient",
  "message": "El número no está registrado en WhatsApp",
  "code": "130472"
}

​

131026 - Usuario Bloqueado

• No hay solución técnica. El usuario debe desbloquear tu número manualmente.
• Considera contactar al usuario por otro medio para resolver cualquier problema.

{
  "error": "user_blocked",
  "message": "El destinatario ha bloqueado este número",
  "code": "131026"
}

​

132000 - Template No Encontrado

1. Verifica el nombre exacto del template en Meta Business Manager
2. Confirma que el template está aprobado (no en revisión o rechazado)
3. Verifica que el código de idioma sea correcto (es_MX, en_US, etc.)
4. Asegúrate de que el template pertenece a tu número de WhatsApp Business

{
  "error": "template_not_found",
  "message": "El template no existe o no está aprobado",
  "code": "132000",
  "details": {
    "template_name": "orden_confirmada",
    "language": "es_MX"
  }
}

​

131048 - Spam Rate Limit

1. Reduce la frecuencia de envío de mensajes
2. Mejora la calidad y relevancia de tus mensajes
3. Asegúrate de que los usuarios hayan dado consentimiento para recibir mensajes
4. Espera 24-48 horas antes de intentar nuevamente

{
  "error": "spam_rate_limit",
  "message": "Tu cuenta ha excedido el límite de spam",
  "code": "131048",
  "action_required": "Reducir frecuencia de envío"
}

​

131052 - Media No Descargable

1. Verifica que la URL sea pública y accesible
2. Asegúrate de que el servidor no bloquee requests de Meta
3. Para archivos privados o grandes, usa POST /media/v1 para subirlos primero

{
  "error": "media_download_failed",
  "message": "No se pudo descargar el archivo multimedia",
  "code": "131052",
  "action_required": "Usar URL pública o subir via /media/v1"
}

​

131051 - Tipo de Media No Soportado

​

131053 - Archivo Demasiado Grande

​

Tabla Resumen de Errores

​

Manejo de Errores en Código

const response = await fetch('https://api.whaapy.com/messages/v1', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+5215512345678',
    content: 'Hola!'
  })
});

const data = await response.json();

if (data.error) {
  switch (data.code) {
    case '131047':
      // Enviar template en su lugar
      await sendTemplate(data.data.conversationId);
      break;
    case '131052':
      // Re-subir media via /media/v1
      const mediaId = await uploadMedia(mediaUrl);
      await sendWithMediaId(mediaId);
      break;
    default:
      console.error('Error:', data.message);
  }
} else {
  console.log('Mensaje enviado:', data.data.id);
}

​

Reintentar Mensajes Fallidos

POST /messages/v1/{message_id}/retry