> ## Documentation Index > Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt > Use this file to discover all available pages before exploring further. # Códigos de Error > Referencia completa de errores de la API de Whaapy y WhatsApp # Códigos de Error Cuando un mensaje falla, Whaapy devuelve información detallada sobre el error incluyendo el código de Meta/WhatsApp, una descripción y pasos para solucionarlo. ## Estructura de Error ```json theme={null} { "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 | Código | Significado | Descripción | | ------ | --------------------- | --------------------------------- | | `200` | OK | Mensaje enviado exitosamente | | `400` | Bad Request | Error de validación en el request | | `401` | Unauthorized | API Key inválida o faltante | | `403` | Forbidden | Sin permisos para este scope | | `404` | Not Found | Recurso no encontrado | | `429` | Too Many Requests | Rate limit excedido | | `500` | Internal Server Error | Error interno del servidor | *** ## Errores de WhatsApp (Meta) Estos códigos provienen directamente de la API de WhatsApp Cloud y se incluyen en el campo `code` de la respuesta. ### 131047 - Ventana de 24 Horas Expirada Este es el error más común. WhatsApp solo permite enviar mensajes de texto libre dentro de las 24 horas posteriores al último mensaje del usuario. **Causa**: Intentaste enviar un mensaje de texto, imagen, video, etc. a un usuario que no te ha escrito en las últimas 24 horas. **Solución**: 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 ```json Ejemplo de respuesta theme={null} { "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" } } ``` El mensaje se guarda en Whaapy con `status: failed`. Una vez que la ventana se reabra (el usuario responde a tu template), puedes usar `POST /messages/v1/{id}/retry` para reenviar el mensaje original. *** ### 131042 - Pago Requerido **Causa**: Tu cuenta de Meta Business no tiene un método de pago configurado o el método de pago falló. **Solución**: 1. Ve a [Meta Business Suite](https://business.facebook.com) 2. Navega a **Configuración** → **Pagos** 3. Agrega o actualiza tu método de pago 4. Verifica que no haya pagos rechazados ```json Ejemplo de respuesta theme={null} { "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 **Causa**: El número de teléfono proporcionado no está registrado en WhatsApp. **Solución**: 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 ```json Ejemplo de respuesta theme={null} { "error": "invalid_recipient", "message": "El número no está registrado en WhatsApp", "code": "130472" } ``` Algunos números corporativos o líneas fijas no pueden recibir mensajes de WhatsApp aunque tengan el formato correcto. *** ### 131026 - Usuario Bloqueado **Causa**: El destinatario ha bloqueado tu número de WhatsApp Business. **Solución**: * 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. ```json Ejemplo de respuesta theme={null} { "error": "user_blocked", "message": "El destinatario ha bloqueado este número", "code": "131026" } ``` *** ### 132000 - Template No Encontrado **Causa**: El template que intentas usar no existe, no está aprobado, o el nombre/idioma no coincide. **Solución**: 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 ```json Ejemplo de respuesta theme={null} { "error": "template_not_found", "message": "El template no existe o no está aprobado", "code": "132000", "details": { "template_name": "orden_confirmada", "language": "es_MX" } } ``` Los templates pueden tardar hasta 24 horas en aprobarse. Si acabas de crear uno, espera a que Meta lo apruebe antes de usarlo. *** ### 131048 - Spam Rate Limit **Causa**: Demasiados mensajes de tu número han sido reportados como spam por los usuarios. **Solución**: 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 ```json Ejemplo de respuesta theme={null} { "error": "spam_rate_limit", "message": "Tu cuenta ha excedido el límite de spam", "code": "131048", "action_required": "Reducir frecuencia de envío" } ``` Si continúas recibiendo este error, Meta puede restringir permanentemente tu cuenta de WhatsApp Business. *** ### 131052 - Media No Descargable **Causa**: Meta no pudo descargar el archivo multimedia desde la URL proporcionada. **Solución**: 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 ```json Ejemplo de respuesta theme={null} { "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" } ``` **Proxy Automático de Whaapy**: Si Meta no puede descargar tu archivo, Whaapy automáticamente intenta descargarlo y re-subirlo a Meta CDN. Sin embargo, esto tiene un límite de 5MB. Para archivos más grandes, usa `/media/v1`. *** ### 131051 - Tipo de Media No Soportado **Causa**: El formato del archivo no es compatible con WhatsApp. **Formatos soportados**: | Tipo | Formatos | | --------- | ----------------------------------------- | | Imagen | JPEG, PNG, WebP | | Video | MP4, 3GPP | | Audio | AAC, MP3, OGG, AMR | | Documento | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT | | Sticker | WebP | *** ### 131053 - Archivo Demasiado Grande **Causa**: El archivo excede el tamaño máximo permitido. **Límites de tamaño**: | Tipo | Máximo | | --------- | ------ | | Imagen | 5 MB | | Video | 16 MB | | Audio | 16 MB | | Documento | 100 MB | | Sticker | 500 KB | *** ## Tabla Resumen de Errores | Código | Error | Causa | Solución Rápida | | -------- | -------------------- | ------------------------------- | ---------------------------- | | `131047` | Ventana Expirada | >24h sin respuesta del usuario | Enviar template | | `131042` | Pago Requerido | Sin método de pago en Meta | Configurar pago | | `130472` | Número Inválido | No tiene WhatsApp | Verificar número | | `131026` | Bloqueado | Usuario te bloqueó | Contactar por otro medio | | `132000` | Template No Existe | Nombre incorrecto o no aprobado | Verificar en Meta | | `131048` | Spam Rate Limit | Muchos reportes de spam | Reducir envíos | | `131052` | Media No Descargable | URL privada o bloqueada | Usar `/media/v1` | | `131051` | Formato No Soportado | Archivo incompatible | Convertir formato | | `131053` | Archivo Grande | Excede límite | Comprimir o usar `/media/v1` | *** ## Manejo de Errores en Código ```javascript Node.js theme={null} 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); } ``` ```python Python theme={null} import requests response = requests.post( 'https://api.whaapy.com/messages/v1', headers={ 'Authorization': 'Bearer wha_TU_API_KEY', 'Content-Type': 'application/json' }, json={ 'to': '+5215512345678', 'content': 'Hola!' } ) data = response.json() if 'error' in data: if data.get('code') == '131047': # Enviar template en su lugar send_template(data['data']['conversationId']) elif data.get('code') == '131052': # Re-subir media via /media/v1 media_id = upload_media(media_url) send_with_media_id(media_id) else: print(f"Error: {data['message']}") else: print(f"Mensaje enviado: {data['data']['id']}") ``` *** ## Reintentar Mensajes Fallidos Cuando un mensaje falla, Whaapy lo guarda con `status: failed`. Una vez que las condiciones permitan su envío, puedes reintentarlo: ```bash theme={null} POST /messages/v1/{message_id}/retry ``` Ver [Reintentar Mensaje](/api-reference/messages/retry) para más detalles.