---
title: "Códigos de error de WhatsApp Cloud API: significado y solución"
description: "Los códigos de error más comunes de WhatsApp Cloud API, de 131047 y 131026 a 132001 y 130429: qué significan, cómo solucionarlos y cuándo no reintentar."
canonical: "https://omnichannels.ai/es/blog/whatsapp-api-error-codes-troubleshooting/"
language: "es"
updated: "2026-10-10"
publisher: "BroadNet Technologies"
brand: "OmniChannels.ai"
category: "whatsapp"
primaryQuery: "whatsapp cloud api error codes"
keywords: ["error WhatsApp 131047", "error WhatsApp 131026", "error WhatsApp 131049", "error WhatsApp 132001", "mensaje de WhatsApp API fallido", "límite de velocidad WhatsApp 130429", "error WhatsApp 131048"]
published: "2026-10-10"
author: "OmniChannels.ai Editorial Team"
reviewer: "BroadNet Messaging Solutions Team"
readingMinutes: 8
answer: "Los errores de WhatsApp Cloud API se agrupan en unas pocas familias: autorización (0, 190, 10), integridad (368, 131031), limitación de velocidad (4, 80007, 130429, 131048, 131049, 131056), problemas de plantilla (132000 a 132016), problemas del destinatario (131026, 131047, 131050) y problemas de la solicitud (131008, 131009). Lea el código y el detalle de error_data y decida: corregir y reintentar, esperar y reintentar, cambiar a una plantilla o a otro canal, o no reintentar nunca."
takeaways: ["El error 131047 significa que la ventana de atención al cliente de 24 horas se ha cerrado; envíe una plantilla aprobada en lugar de un mensaje libre.", "El error 131050 significa que el usuario ha dejado de recibir mensajes de marketing; Meta indica que no se reintente.", "El error 131049 es un límite de marketing por usuario; Meta aconseja esperar al menos 24 horas antes de volver a enviar.", "Los errores 132000 y 132012 casi siempre se deben a que el número de variables o su formato no coincide con la plantilla aprobada.", "Algunos errores se devuelven de forma síncrona en la respuesta de la API; otros llegan después en los webhooks de estado con el estado failed, así que debe registrar ambos."]
faq: 
  - q: "¿Qué significa el error 131047 de WhatsApp?"
    a: "El error 131047 significa que han pasado más de 24 horas desde que el destinatario escribió por última vez a su número, por lo que la ventana de atención al cliente está cerrada. Ya no se permiten mensajes de texto libres, archivos multimedia ni mensajes interactivos. Envíe una plantilla aprobada, idealmente una de utilidad que invite al cliente a responder, lo que reabre la ventana cuando conteste."
  - q: "¿Por qué recibo el error 131026 si el número está en WhatsApp?"
    a: "Meta describe 131026 como imposibilidad de entregar el mensaje. Entre las causas están un número que no está en WhatsApp, un destinatario que no ha aceptado los últimos términos o una versión de WhatsApp desactualizada. Un prefijo de país incorrecto o un formato local también son culpables frecuentes. Valide el número en formato internacional, pida al cliente que actualice la aplicación o use SMS o correo electrónico."
  - q: "¿Cuál es la diferencia entre 130429 y 131056?"
    a: "130429 significa que su número ha alcanzado su límite de rendimiento en Cloud API, es decir, envía demasiado rápido en conjunto; reduzca el ritmo y use una cola. 131056 significa que ha enviado demasiados mensajes al mismo destinatario en poco tiempo; los demás destinatarios no se ven afectados. Solucione 130429 con control de velocidad, y 131056 espaciando los mensajes a ese usuario."
  - q: "¿Debo reintentar automáticamente los mensajes de WhatsApp fallidos?"
    a: "Solo en errores transitorios como 131000 (desconocido), 131016 (servicio no disponible), 130429 (rendimiento) y 4 u 80007 (límites de velocidad), con retroceso exponencial. No reintente nunca automáticamente 131050 (baja del marketing), 131026 sin cambiar nada, errores de plantilla ni restricciones de política 368. Los reintentos a ciegas malgastan dinero, molestan a los usuarios y pueden perjudicar la calidad."
  - q: "¿Dónde puedo ver el detalle completo del error?"
    a: "Los errores síncronos llegan en la respuesta de la API con code, message y error_data. Los fallos asíncronos llegan al webhook messages con el estado failed y un array errors con el código, el título y los detalles. Registre el objeto completo y no solo el código, porque el campo details suele señalar el parámetro o el problema de archivo multimedia exacto."
sources: 
  - title: "Códigos de error — WhatsApp Cloud API, Meta for Developers"
    url: "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes"
  - title: "Referencia del webhook de estado de mensajes — Meta for Developers"
    url: "https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/messages/status"
  - title: "Acerca de la plataforma: límites de velocidad y cifrado — Meta for Developers"
    url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform"
---

# Códigos de error de WhatsApp Cloud API: significado y solución

Canonical: https://omnichannels.ai/es/blog/whatsapp-api-error-codes-troubleshooting/
Language: es
Publisher: OmniChannels.ai by BroadNet Technologies

Esta guía está pensada para desarrolladores y equipos de operaciones de mensajería que ven mensajes de WhatsApp fallidos y necesitan saber con rapidez si deben corregir la solicitud, esperar, cambiar el tipo de mensaje o parar. Todos los códigos siguientes se han contrastado con la referencia de códigos de error de Cloud API de Meta; los códigos y su redacción cambian, así que confírmelos en esa página antes de fijar lógica en su código.

## ¿Dónde aparecen los errores de WhatsApp Cloud API?

Los errores aparecen en dos lugares y debe capturar ambos. Los errores de solicitud llegan de inmediato en la respuesta de la API; los de entrega llegan más tarde en un webhook de estado.

- **Errores síncronos.** La solicitud de envío se rechaza y la respuesta contiene un objeto `error` con `code`, `message`, `type` y, a menudo, `error_data.details`. Ejemplos típicos: tokens caducados, parámetros que faltan y desajustes con la plantilla.
- **Errores asíncronos.** La solicitud de envío tiene éxito y devuelve un ID de mensaje, pero un webhook posterior informa `status: failed` con un array `errors`. Ejemplos típicos: ventanas de atención cerradas, destinatarios no alcanzables y límites de marketing.

Un error habitual es registrar solo la respuesta HTTP. El equipo cree entonces que una campaña ha salido bien porque cada solicitud devolvió un ID de mensaje, mientras que cientos de mensajes han fallado en los webhooks. Para entender cómo se relacionan los estados, consulte [enviado, entregado, leído y fallido explicados](/es/blog/message-delivery-status-explained/).

## ¿Cuáles son los códigos de error de WhatsApp más comunes?

La tabla recoge los códigos que encuentran la mayoría de los equipos, agrupados según lo que debe hacer a continuación. Las descripciones parafrasean la referencia de Meta.

| Código | Significado | Solución | ¿Reintentar? |
|---|---|---|---|
| 0 | No se pudo autenticar al usuario de la app; token caducado o revocado | Generar un nuevo token de acceso | Tras corregir |
| 190 | El token de acceso ha caducado | Usar un token de usuario del sistema que no caduque, renovarlo | Tras corregir |
| 3, 10, 200–299 | Falta un permiso o una capacidad | Revisar los permisos del token en el depurador de tokens de acceso | Tras corregir |
| 368 | WABA restringida o desactivada por infracción de política | Revisar la aplicación de políticas en WhatsApp Manager; apelar si es un error | No |
| 131031 | Cuenta bloqueada, por ejemplo por fallo de verificación de política o de datos | Revisar el estado de la cuenta; resolverlo con Meta | No |
| 4 | La app alcanzó su límite de llamadas a la API | Reducir el volumen de solicitudes; revisar el App Dashboard | Sí, más tarde |
| 80007 | La WABA alcanzó su límite de velocidad | Reducir el volumen de solicitudes; reintentar más tarde | Sí, más tarde |
| 130429 | Se alcanzó el rendimiento de Cloud API para el número | Poner en cola y reducir el ritmo de envío | Sí, con retroceso |
| 131048 | Límite por spam: restricciones en los mensajes de este número | Revisar la calidad en WhatsApp Manager; mejorar contenido y segmentación | No de inmediato |
| 131049 | No entregado «para mantener un nivel saludable de interacción en el ecosistema» | Esperar al menos 24 horas antes de reenviar | No antes de 24 h |
| 131056 | Demasiados mensajes al mismo destinatario en poco tiempo | Espaciar los mensajes a ese usuario | Sí, más tarde |
| 131000 | Error desconocido | Reintentar; abrir un ticket de soporte si persiste | Sí, de forma limitada |
| 131016 | Servicio temporalmente no disponible | Consultar la página de estado de Meta; reintentar | Sí, con retroceso |
| 131008 | Falta un parámetro obligatorio | Comparar el payload con la referencia del endpoint | Tras corregir |
| 131009 | Valor de parámetro no válido | Revisar los valores, por ejemplo el formato del número o los ID | Tras corregir |
| 131021 | El remitente y el destinatario son el mismo número | Enviar a otro número | No |
| 131026 | No se pudo entregar el mensaje | Verificar el número, pedir al usuario que actualice WhatsApp o usar otro canal | No tal cual |
| 131042 | Problema con el método de pago | Corregir la facturación: cuenta de pago, línea de crédito, moneda | Tras corregir |
| 131045 / 133010 | Número no registrado en la plataforma | Registrar el número de teléfono de empresa | Tras corregir |
| 131047 | Han pasado más de 24 horas desde la última respuesta del usuario | Enviar una plantilla aprobada | Como plantilla |
| 131050 | El usuario dejó de recibir mensajes de marketing | No reintentar; respetar su preferencia | Nunca |
| 131051 | Tipo de mensaje no admitido | Usar un tipo admitido | Tras corregir |
| 131052 | No se pudo descargar el archivo multimedia enviado por el usuario | Pedir al usuario que lo reenvíe | n/a |
| 131053 | No se pudo subir el archivo multimedia de su mensaje | Revisar el tipo MIME, el tamaño y la URL | Tras corregir |
| 131057 | Cuenta en modo de mantenimiento | Esperar; puede ocurrir durante una ampliación de rendimiento | Sí, más tarde |
| 132000 | El número de variables no coincide con la plantilla | Enviar exactamente el número de parámetros definido | Tras corregir |
| 132001 | Plantilla inexistente en ese idioma o no aprobada | Revisar nombre, código de idioma y estado | Tras corregir |
| 132005 | Texto traducido demasiado largo | Acortar la traducción de la plantilla | Tras corregir |
| 132007 | El contenido de la plantilla infringe la política | Editar según las reglas de revisión de plantillas | Tras corregir |
| 132012 | Valores de variables con formato incorrecto | Ajustarse al formato esperado | Tras corregir |
| 132015 | Plantilla pausada por baja calidad | Editar el contenido para mejorar la calidad | Tras editar |
| 132016 | Plantilla desactivada de forma permanente tras pausas repetidas | Crear una plantilla nueva con contenido distinto | No |
| 135000 | Error desconocido en los parámetros de la solicitud | Revisar la sintaxis de la solicitud; contactar con soporte | Tras corregir |

## ¿Cómo se solucionan los errores que causan la mayoría de las campañas fallidas?

En la práctica, un puñado de códigos provoca casi todos los fallos. Cada uno tiene una regla de decisión clara.

### 131047: la ventana de atención está cerrada

El cliente escribió por última vez hace más de 24 horas. El texto libre, los archivos multimedia y los mensajes interactivos solo se permiten dentro de la ventana de atención al cliente de 24 horas; fuera de ella hay que usar una plantilla aprobada; consulte [la ventana de atención al cliente de 24 horas](/es/blog/whatsapp-24-hour-customer-service-window/). Los agentes se topan con esto a menudo al responder a un chat antiguo. Muéstreles el estado de la ventana y ofrezca un selector de plantillas cuando haya caducado.

### 131026: mensaje no entregable

Empiece por la higiene de los números: formato internacional, prefijo de país correcto y sin cero inicial tras el prefijo. Después asuma que algunos números sencillamente no están en WhatsApp o tienen una versión antigua de la aplicación. En mensajes urgentes, como los OTP, recurra al SMS. Consulte [WhatsApp, SMS y RCS](/es/blog/whatsapp-vs-sms-vs-rcs/).

### 131049 y 131050: límites de marketing y bajas

Ambos afectan a los mensajes de marketing. 131050 es la decisión explícita del usuario de dejar de recibirlos; excluya a esos usuarios del marketing y suscríbase al webhook de preferencias de usuario de Meta. 131049 significa que Meta decidió no entregar para proteger la interacción de los usuarios; Meta aconseja esperar al menos 24 horas, y los reintentos más tempranos probablemente fallarán de nuevo. Reduzca la frecuencia y mejore la relevancia en lugar de reenviar.

### 130429, 131048 y 131056: enviar demasiado rápido o demasiado

130429 es rendimiento: ponga los mensajes en cola y aplique retroceso. 131056 es a nivel de pareja: escribe demasiado a una misma persona. 131048 es una señal de calidad del número remitente y requiere corregir contenido y segmentación, no reintentar. Consulte [límites de mensajería y calificación de calidad](/es/blog/whatsapp-messaging-limits-quality-rating/).

### 132000, 132001 y 132012: desajustes con la plantilla

Casi siempre son errores de integración. El nombre de la plantilla, el código de idioma (por ejemplo `ar` frente a `en_US`) y el número de variables deben coincidir exactamente con lo aprobado. Cree una prueba que envíe cada plantilla con valores de ejemplo cada vez que la edite.

## Una política de reintentos que puede implementar

Use esta lista de verificación para clasificar cada fallo automáticamente.

1. **Registre** el código, el título, `error_data.details`, el ID del mensaje, el destinatario y el nombre de la plantilla.
2. **No reintente nunca** 131050, 131021, 132016, 368 y 131031. Avise de inmediato a un administrador de 368 y 131031.
3. **Corrija y luego reintente** los errores de autorización (0, 190, 10), de parámetros (131008, 131009, 135000), de plantilla (132000 a 132015) y de facturación (131042). Alerte al equipo responsable.
4. **Aplique retroceso y reintente** 130429, 4, 80007, 131016 y 131057 con retroceso exponencial y un tope.
5. **Cambie de canal o de tipo de mensaje** en 131047 (plantilla) y 131026 (SMS o correo electrónico).
6. **Espere 24 horas o más** en 131049 y revise la frecuencia de las campañas.
7. **Informe** de los fallos por código en los informes de campaña, no como un único total de «fallidos».

## Ejemplo práctico: la promoción fallida de un minorista de Riad

Ejemplo sintético. «Najd Home» envía una plantilla de marketing a 20.000 clientes que han dado su consentimiento (opt-in). La API acepta todas las solicitudes, pero los webhooks de estado muestran unos 1.400 fallos.

Agrupados por código, el panorama es claro. El grupo más numeroso es 131049, así que el equipo excluye a esos usuarios de los dos envíos siguientes y reduce la frecuencia semanal. Un grupo menor es 131026; el análisis revela que muchos números estaban guardados con un cero inicial local, algo que se resuelve con una corrección de normalización. Varios usuarios con 131050 quedan suprimidos del marketing de forma permanente. Algunos errores 130429 provenían de la ráfaga inicial, por lo que ahora el envío se dosifica mediante una cola.

## Errores comunes y límites reales

- **Tratar todos los fallos como reintentables.** Malgasta presupuesto y puede reducir la calidad.
- **Fijar en el código los textos de Meta.** Meta actualiza títulos y descripciones; base la lógica en el código numérico y mantenga una tabla de consulta que pueda actualizar.
- **Ignorar `error_data.details`.** A menudo señala el parámetro defectuoso exacto.
- **No todos los fallos tienen solución.** Algunos destinatarios no son alcanzables por WhatsApp, y Meta no explica todas las decisiones 131049. Prevea un canal alternativo.

## Cómo ayuda OmniChannels.ai

OmniChannels.ai, con la tecnología de BroadNet Technologies, ofrece informes de entrega (DLR) en vistas resumida y avanzada, con filtros y exportación a CSV, para analizar los mensajes fallidos por campaña. El respaldo entre canales puede reenviar por RCS o SMS cuando falla WhatsApp, y las plantillas se previsualizan en una maqueta de teléfono y se siguen hasta su aprobación, lo que reduce los errores de desajuste. Los [webhooks](/developers/webhooks/) notifican los estados FAILED y REJECTED en un único formato normalizado, y la [documentación para desarrolladores](/developers/) pública incluye una referencia de [errores y límites](/developers/errors-and-limits/).