La API de la nube se basa en la API Graph. Por lo tanto, si no sabes cómo administrar las respuestas de error de la API Graph, consulta la documentación sobre la administración de errores de esta API.
Por lo general, te recomendamos que compiles la lógica de manejo de errores de tu app en función de valores code
y propiedades de carga útil details
. Estas propiedades y sus valores son indicadores más precisos de los errores subyacentes.
Los títulos de los códigos, que no tienen una propiedad específica en las cargas útiles de respuestas de error de la API, se incluyen como parte del valor message
. No obstante, te recomendamos que la lógica de manejo de errores no se base en los títulos, ya que estos quedarán obsoletos con el tiempo.
Los errores de la API de la nube se devuelven de forma sincrónica como una respuesta de la API Graph, de forma asincrónica a través de Webhook o, a veces, a través de ambos métodos.
Cuando se trabaja con la API de la nube, se recomienda supervisar tanto la respuesta de la API Graph como el webhook de messages
para el manejo de errores. Si estás suscrito al campo de webhook messages
, recibirás una notificación de errores cuando se produzcan con tipos de errores asincrónicos admitidos.
Los errores de la API de la nube se pueden ver en los siguientes objetos de webhook:
API de la nube
entry.changes.value.errors
entry.changes.value.messages.errors
API de instalaciones locales
errors
Sintaxis de respuesta de error
{ "error": { "message": "<MESSAGE>", "type": "<TYPE>", "code": <CODE>, "error_data": { "messaging_product": "whatsapp", "details": "<DETAILS>" }, "error_subcode": <ERROR_SUBCODE> "fbtrace_id": "<FBTRACE_ID>" } }
Propiedad | Tipo de valor | Descripción |
---|---|---|
| Número entero | Código de error. Recomendamos que bases la administración de errores de tu app en códigos de error, no en subcódigos ni códigos de estado de respuesta HTTP. |
| Cadena | Descripción del error y descripción de la causa más probable del error. También puede incluir información sobre cómo abordar el error, por ejemplo, qué parámetro no es válido o qué valores son aceptables. |
| Número entero | Obsoleto. No se devolverá en las respuestas de las versiones 16.0 y posteriores. Subcódigo de la API Graph. No todas las respuestas incluirán un subcódigo, por lo que te recomendamos que compiles tu lógica de manejo de errores en función de las propiedades |
| Cadena | Identificador de seguimiento que puedes incluir cuando te comunicas con la asistencia directa. El identificador puede ayudarnos a depurar el error. |
| Cadena | Combinación del código de error y su título. Por ejemplo: |
| Cadena | Productos de mensajes. Será siempre la cadena |
| Cadena | Tipo de error. |
{ "error": { "message": "(#130429) Rate limit hit", "type": "OAuthException", "code": 130429, "error_data": { "messaging_product": "whatsapp", "details": "Message failed to send because there were too many messages sent from this phone number in a short period of time" }, "error_subcode": 2494055, "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam" } }
Código | Descripción | Posibles soluciones | Código de estado HTTP |
---|---|---|---|
Excepción de autenticación | No se pudo autenticar al usuario de la app. | En general, se debe a que el token de acceso incluido caducó o se invalidó, o bien a que el usuario de la app cambió una configuración para evitar que todas las apps accedan a sus datos. Te recomendamos obtener un nuevo token de acceso. |
No autorizado |
Método de la API | Problema de función o permisos. | Usa el depurador de token de acceso para comprobar que tu app tenga los permisos que requiere el punto de conexión. Consulta Solución de problemas. |
Error de servidor interno |
Permiso denegado | No se otorgó el permiso o se eliminó. | Usa el depurador de tokens de acceso para comprobar que tu app tenga los permisos que requiere el punto de conexión. Consulta Solución de problemas. Asegúrate de que el número de teléfono usado para configurar la clave pública del negocio esté en la lista de autorizados. |
Prohibido |
El token de acceso caducó | El token de acceso caducó. |
No autorizado | |
Permiso de la API | No se otorgó el permiso o se eliminó. | Usa el depurador de tokens de acceso para comprobar que tu app tenga los permisos que requiere el punto de conexión. Consulta Solución de problemas. |
Prohibido |
Código | Descripción | Posibles soluciones | Código de estado HTTP |
---|---|---|---|
Demasiadas llamadas a la API | La app alcanzó el límite de frecuencia de llamadas a la API. | Carga la app en el panel de apps y consulta la sección Límite de frecuencia de la app para comprobar que la app haya alcanzado el límite de frecuencia. Si es así, vuelve a intentarlo más tarde o reduce la frecuencia o la cantidad de consultas a la API que realiza la app. |
Solicitud incorrecta |
Problemas de límite de frecuencia | La cuenta de WhatsApp Business alcanzó el límite de frecuencia. | Consulta los límites de frecuencia de la cuenta de WhatsApp Business. Vuelve a intentarlo más tarde o reduce la frecuencia o la cantidad de consultas a la API que realiza la app. |
Solicitud incorrecta |
Se alcanzó el límite de frecuencia | Se alcanzó el rendimiento de mensajes de la API de la nube. | La app alcanzó el límite de rendimiento de la API. Consulta Rendimiento. Vuelve a intentarlo más tarde o reduce la frecuencia con la que la app envía mensajes. |
Solicitud incorrecta |
Se alcanzó el límite de frecuencia de spam | No se pudo enviar el mensaje, porque hay restricciones relacionadas con la cantidad de mensajes que se pueden enviar desde este número de teléfono. Esto se puede deber a que se bloquearon o marcaron como spam demasiados mensajes anteriores. | Comprueba el estado de calidad en el administrador de WhatsApp y consulta la documentación sobre límites de frecuencia en función de la calidad para obtener más información. |
Solicitud incorrecta |
Se alcanzó el límite de frecuencia de la combinación de cuenta de empresa y cuenta de cliente | Demasiados mensajes enviados desde el número de teléfono del emisor al mismo número de teléfono del destinatario en poco tiempo. | Espera y reintenta la operación si quieres enviar mensajes al mismo número de teléfono. Todavía puedes enviar mensajes a diferentes números de teléfono sin esperar. |
Solicitud incorrecta |
Se excedió el límite de frecuencia de anulación del registro del registro de cuenta | Falló el registro o la anulación del registro debido a que se realizaron demasiados intentos en relación con este número de teléfono en un período de tiempo corto. | El número de teléfono de la empresa está siendo bloqueado porque alcanzó el límite de intentos de registro/anulación del registro. Inténtalo de nuevo cuando el número esté desbloqueado. Consulta "Limitaciones" en el documento Registro. |
Solicitud incorrecta |
Código | Descripción | Posibles soluciones | Código de estado HTTP |
---|---|---|---|
Bloqueado temporalmente por infracción de las políticas | Se restringió o inhabilitó la cuenta de WhatsApp Business asociada con la app debido a una infracción de la política de la plataforma. | Consulta el documento Aplicación de políticas para obtener información sobre las infracciones de las políticas y cómo resolverlas. |
Prohibido |
La cuenta de empresa no puede enviar mensajes a los usuarios de este país. | La cuenta de WhatsApp Business no puede enviar mensajes a los usuarios de determinados países. | Consulta Política de mensajes de WhatsApp Business para obtener información sobre los países cuyos usuarios pueden recibir tus mensajes según la categoría de tu empresa. |
Prohibido |
Se bloqueó la cuenta | Se restringió o inhabilitó la cuenta de WhatsApp Business asociada con la app debido a una infracción de una política de la plataforma, o no se pudieron verificar los datos incluidos en la solicitud en referencia a los datos configurados en la cuenta de WhatsApp Business (p. ej., el PIN de verificación en dos pasos incluido en la solicitud es incorrecto). | Consulta el documento Aplicación de políticas para obtener más información sobre las infracciones de las políticas y cómo resolverlas. También puedes usar la API de estado general, que puede proporcionar información adicional sobre la razón o las razones del bloqueo de la cuenta. |
Prohibido |
Código | Descripción | Posibles soluciones | Código de estado HTTP |
---|---|---|---|
API desconocida | Solicitud no válida o posible error del servidor. | Consulta la página Estado de la Plataforma de WhatsApp Business para obtener información del estado de la API. Si no se produjeron interrupciones del servidor, consulta la referencia del punto de conexión y verifica que la solicitud tenga el formato correcto y cumpla con todos los requisitos del punto de conexión. |
Solicitud incorrecta |
Servicio de API | Temporal debido a tiempo de inactividad o sobrecarga. | Consulta la página Estado de la Plataforma de WhatsApp Business para obtener información sobre el estado de la API antes de volver a intentarlo. |
Servicio no disponible |
Valor no válido del parámetro | El número de teléfono de la empresa se eliminó. | Verifica que el número de teléfono de la empresa sea correcto. |
Solicitud incorrecta |
Parámetro inválido | En la solicitud, se incluyeron uno o más parámetros no admitidos o mal escritos. | Consulta la referencia del punto de conexión para determinar qué parámetros se admiten y cómo se escriben. Cuando configures la clave pública del negocio, asegúrate de que sea una clave pública de RSA válida de 2.048 bits en formato PEM. Asegúrate de que no haya ninguna incongruencia entre el identificador del número de teléfono que estás registrando y el identificador del número de teléfono almacenado anteriormente. Asegúrate de que el parámetro no supere ninguna restricción de longitud para el tipo. |
Solicitud incorrecta |
El número del usuario es parte de un experimento | El mensaje no se envió como parte de un experimento. | Consulta Experimento con mensaje de marketing. |
Solicitud incorrecta |
Se produjo un error. | No se pudo enviar el mensaje debido a un error desconocido. Si se produce cuando configuras una clave pública del negocio, quiere decir que no se pudo calcular la firma, no se pudo llamar al punto de conexión de GraphQL o el punto de conexión de GraphQL devolvió un error. | Vuelve a intentarlo. Si el error persiste, abre un ticket de asistencia directa. |
Error de servidor interno |
Acceso denegado | No se otorgó el permiso o se eliminó. | Usa el depurador de tokens de acceso para comprobar que tu app tenga los permisos que requiere el punto de conexión. Consulta Solución de problemas. |
Prohibido |
Falta un parámetro obligatorio | Falta un parámetro obligatorio en la solicitud. | Consulta la referencia del punto de conexión para determinar qué parámetros son obligatorios. |
Solicitud incorrecta |
El valor del parámetro no es válido | Uno o más valores del parámetro no son válidos. | Consulta la referencia del punto de conexión para determinar qué valores son compatibles con cada parámetro y consulta los números de teléfono para obtener más información sobre cómo agregar un número de teléfono a una cuenta de WhatsApp Business. |
Solicitud incorrecta |
Servicio no disponible | Un servicio no está disponible temporalmente. | Consulta la página Estado de la Plataforma de WhatsApp Business para ver la información del estado de la API antes de volver a intentarlo. |
Error de servidor interno |
El destinatario no puede ser el emisor | El número de teléfono del emisor y el del destinatario son el mismo. | Envía un mensaje a un número de teléfono que no sea el del emisor. |
Solicitud incorrecta |
El mensaje no se puede enviar | No se puede enviar el mensaje. Entre las posibles razones, se incluyen las siguientes:
| Utiliza un método de comunicación que no sea WhatsApp y pídele al usuario de WhatsApp que realice lo siguiente:
|
Solicitud incorrecta |
Elegibilidad de la empresa: problema de pago | Hubo un error relacionado con tu método de pago. | Consulta Información sobre la facturación de una cuenta de WhatsApp Business y verifica si configuraste la facturación de manera correcta. Problemas comunes:
|
Solicitud incorrecta |
Certificado incorrecto | No se pudo enviar el mensaje debido a un error de registro del número de teléfono. | Registra el número de teléfono antes de volver a intentarlo. |
Error de servidor interno |
Mensajes de nueva interacción | Pasaron más de 24 horas desde la última vez en que el destinatario envió una respuesta al número del emisor. | Envía al destinatario un mensaje iniciado por la empresa mediante una plantilla de mensaje. |
Solicitud incorrecta |
Meta decidió no entregar el mensaje. | Este mensaje no se entregó para mantener una interacción adecuada en el ecosistema. | Si recibes este código de error y sospechas que se debe a que alcanzaste el límite, no vuelvas a intentarlo inmediatamente. En cambio, aumenta progresivamente el tiempo entre los intentos hasta que el mensaje se entregue, ya que el límite puede estar vigente por diferentes períodos. Consulta Límites de mensajes de plantillas de marketing por usuario para obtener información adicional. |
Solicitud incorrecta |
Tipo de mensaje no compatible | Tipo de mensaje no compatible. | Consulta Mensajes para obtener información sobre los tipos de mensajes compatibles antes de volver a intentarlo con un tipo de mensaje compatible. |
Solicitud incorrecta |
Error de descarga del archivo multimedia | No se pudo descargar el contenido multimedia que envió el usuario. | No pudimos descargar el contenido multimedia incluido en el mensaje del usuario de WhatsApp. Para obtener más información, consulta el valor Pídele al usuario de WhatsApp que te envíe el archivo multimedia por un canal diferente a WhatsApp. |
Solicitud incorrecta |
Error al subir el archivo multimedia | No se pudo subir el contenido multimedia que se usó en el mensaje. | No pudimos subir el contenido multimedia por uno o más motivos, como un tipo de contenido multimedia no admitido. Para obtener más información, consulta el valor Te recomendamos que inspecciones todos los archivos con contenido multimedia que provoquen errores y que confirmes que, de hecho, sean admitidos. Por ejemplo, en UNIX, puedes utilizar la inspección de archivos a través de la línea de comandos para determinar el tipo de MIME:
Luego, puedes confirmar si se admite el tipo MIME. Consulta los tipos de archivos multimedia compatibles. |
Solicitud incorrecta |
Cuenta en modo de mantenimiento | La cuenta comercial está en modo de mantenimiento. | La cuenta de WhatsApp Business está en modo de mantenimiento. Un motivo de esta situación podría ser que la cuenta se encuentra actualizando su volumen. |
Solicitud incorrecta |
No coincide el conteo de parámetros de plantilla | El número de valores de parámetros variables incluidos en la solicitud no coincide con el número de parámetros variables definidos en la plantilla. | Consulta las normas de las plantillas de mensajes y asegúrate de que en la solicitud se incluyan todos los valores de parámetros variables que se definieron en la plantilla. |
Solicitud incorrecta |
La plantilla no existe | La plantilla no existe en el idioma especificado o no se aprobó. | Asegúrate de que la plantilla haya sido aprobada y de que el nombre y el idioma sean correctos. Asegúrate de seguir las normas de las plantillas de mensajes. |
No se encontró |
Texto de plantilla traducido demasiado largo | El texto traducido es demasiado largo. | Consulta el administrador de WhatsApp para comprobar que la plantilla se haya traducido. Consulta Calificación de calidad y estado de la plantilla. |
Solicitud incorrecta |
Se infringió la política de caracteres de formato de plantilla | El contenido de la plantilla infringe una política de WhatsApp. | Consulta los motivos de rechazo para determinar las causas posibles de la infracción. |
Solicitud incorrecta |
No coincide el formato de parámetro de plantilla | Los valores de parámetros variables tienen un formato incorrecto. | Los valores de los parámetros variables incluidos en la solicitud no utilizan el formato especificado en la plantilla. Consulta las normas de las plantillas de mensajes. |
Solicitud incorrecta |
La plantilla está en pausa | La plantilla está en pausa debido a que su calidad es baja, por lo que no se puede enviar en un mensaje de plantilla. | Edita la plantilla para mejorar su calidad y vuelve a intentarlo una vez que esté aprobada. |
Solicitud incorrecta |
La plantilla está desactivada | La plantilla se pausó demasiadas veces debido a que su calidad es baja y ahora se desactivó de manera permanente. | Crea una nueva plantilla con otro contenido. |
Solicitud incorrecta |
Proceso bloqueado | El proceso se encuentra en estado bloqueado. | Corrige el proceso. |
Solicitud incorrecta |
Proceso limitado | El proceso está limitado, y en la última hora ya se enviaron 10 mensajes que usan este proceso. | Corregir el proceso |
Solicitud incorrecta |
Anulación del registro incompleta | Falló un intento anterior de anulación del registro. | Anula el registro del número otra vez para poder registrarte. |
Error de servidor interno |
Servidor no disponible temporalmente | El servidor no está disponible temporalmente. | Consulta la página Estado de la Plataforma de WhatsApp Business para ver la información del estado de la API y ver el valor de la respuesta |
Servicio no disponible |
No coincide el PIN de verificación en dos pasos | El PIN de verificación en dos pasos es incorrecto. | Comprueba que el PIN de verificación en dos pasos incluido en la solicitud sea correcto. Para restablecer el PIN de verificación en dos pasos, realiza lo siguiente:
|
Solicitud incorrecta |
Es necesario volver a verificar el número de teléfono | Para registrar el número de teléfono, primero se necesita verificarlo. | Verifica el número de teléfono para poder registrarlo. |
Solicitud incorrecta |
Demasiados intentos incorrectos de ingreso del PIN de verificación en dos pasos | Demasiados intentos incorrectos de ingreso del PIN de verificación en dos pasos en este número de teléfono. | Vuelve a intentarlo luego del tiempo especificado en el valor de respuesta |
Solicitud incorrecta |
Intento de ingreso del PIN de verificación en dos pasos demasiado rápido | El PIN de verificación en dos pasos se ingresó demasiado rápido. | Consulta el valor de respuesta |
Solicitud incorrecta |
Número de teléfono no registrado | Número de teléfono no registrado en la Plataforma de WhatsApp Business. | Registra el número de teléfono para volver a intentarlo. |
Solicitud incorrecta |
Espera unos minutos antes de volver a intentar registrar este número de teléfono. | El número de teléfono que intentas registrar se eliminó recientemente, y esta acción todavía no se completó. | Espera 5 minutos antes de volver a enviar la solicitud. |
Solicitud incorrecta |
Error de uso genérico | No se pudo enviar el mensaje debido a un error desconocido relacionado con los parámetros de la solicitud. | Consulta la referencia del punto de conexión para determinar si estás consultando el punto de conexión con la sintaxis correcta. Comunícate con el servicio de atención al cliente si sigues recibiendo este código de error en la respuesta. |
Solicitud incorrecta |