La API de nube se basa en la API Graph, por lo que si no tienes experiencia con la gestión de las respuestas de error de la API Graph, consulta la documentación sobre gestión de errores de la API Graph.
En general, te recomendamos que desarrolles la lógica de gestión de errores de tu aplicación en torno a los valores de code
y las propiedades de la carga útil de details
. Estas propiedades y los valores correspondientes indican el error subyacente de forma más precisa.
Los títulos de los códigos, que no tienen una propiedad dedicada en las cargas útiles de las respuestas de error de la API, se incluyen como parte del valor de message
. No obstante, te recomendamos que no te bases en los títulos para la lógica de gestión de errores, ya que con el tiempo se retirarán.
Los errores de la API de nube se devuelven de forma síncrona como respuesta de la API Graph, de forma asíncrona mediante webhooks o, a veces, de ambas formas.
Al trabajar con la API de nube, es aconsejable supervisar tanto la respuesta de la API Graph como el webhook messages
para gestionar los errores. Si te has suscrito al campo del webhook messages
, recibirás notificaciones de errores conforme se produzcan para los tipos de errores asíncronos admitidos.
Los errores de la API de nube pueden aparecer en los siguientes objetos de webhooks:
API de nube
entry.changes.value.errors
entry.changes.value.messages.errors
API local
errors
Sintaxis de la 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 |
---|---|---|
| Entero | Código de error. Te recomendamos que desarrolles la gestión de errores de tu aplicación en torno a los códigos de error y no a los subcódigos o los códigos de estado de las respuestas HTTP. |
| Cadena | Descripción del error y descripción del motivo más probable del error. También puede incluir información sobre cómo abordar el error, como el parámetro que no es válido o los valores que se aceptan. |
| Entero | Retirada. No se devolverá en las respuestas de la versión 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 desarrolles la lógica de gestión de errores en torno a los valores de |
| Cadena | Identificador de seguimiento que puedes incluir al ponerte en contacto con el equipo de asistencia directa. Este identificador puede ayudarnos a depurar el error. |
| Cadena | Combinación del código y el título del error. Por ejemplo: |
| Cadena | Producto de mensajes. En el caso de las respuestas de la API de nube, siempre será 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 |
---|---|---|---|
AuthException | No se puede autenticar al usuario de la aplicación. | Normalmente, significa que el identificador de acceso incluido ha caducado o se ha invalidado, o que el usuario de la aplicación ha cambiado una configuración para evitar que todas las aplicaciones accedan a sus datos. Te recomendamos que obtengas un nuevo identificador de acceso. |
No autorizado |
Método de la API | Problema con una función o permisos. | Utiliza el depurador de identificadores de acceso para verificar que los permisos que necesita el extremo se hayan concedido a la aplicación. Consulta Solución de problemas. |
Error interno del servidor |
Permiso denegado | No se ha concedido un permiso o se ha eliminado. | Utiliza el depurador de identificadores de acceso para verificar que los permisos que necesita el extremo se hayan concedido a la aplicación. Consulta Solucionar problemas. Asegúrate de que el número de teléfono utilizado para establecer la clave pública de la empresa esté en la lista de permitidos. |
Prohibido |
El identificador de acceso ha caducado | El identificador de acceso ha caducado. |
No autorizado | |
Permiso de la API | No se ha concedido un permiso o se ha eliminado. | Utiliza el depurador de identificadores de acceso para verificar que los permisos que necesita el extremo se hayan concedido a la aplicación. Consulta Solucionar problemas. |
Prohibido |
Código | Descripción | Posibles soluciones | Código de estado HTTP |
---|---|---|---|
Demasiadas llamadas a la API | La aplicación ha alcanzado el límite de frecuencia de llamadas a la API. | Carga la aplicación en el panel de aplicaciones y consulta la sección Limitación de frecuencia de la aplicación para verificar si ha alcanzado el límite de frecuencia. Si lo ha alcanzado, vuelve a intentarlo más tarde o reduce la frecuencia o la cantidad de consultas a la API que realiza la aplicación. |
Solicitud incorrecta |
Problemas de límite de frecuencia | La cuenta de WhatsApp Business ha alcanzado 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 aplicación. |
Solicitud incorrecta |
Se ha alcanzado el límite de frecuencia | Se ha alcanzado el rendimiento de los mensajes de la API de nube. | La aplicación ha alcanzado el límite de rendimiento de la API. Consulta Rendimiento. Vuelve a intentarlo más tarde o reduce la frecuencia con la que la aplicación envía mensajes. |
Solicitud incorrecta |
Se ha alcanzado el límite de frecuencia de spam | El mensaje no se pudo enviar porque hay restricciones respecto a la cantidad de mensajes que se pueden enviar desde este número de teléfono. Esto se puede deber a que muchos mensajes anteriores se bloquearon o se marcaron como spam. | Comprueba el estado de calidad en el Administrador de WhatsApp y consulta la documentación sobre los límites de frecuencia basados en la calidad para obtener más información. |
Solicitud incorrecta |
Se ha alcanzado el límite de frecuencia del par (cuenta empresarial, cuenta de consumidor) | Se han enviado demasiados mensajes desde el número de teléfono del remitente al mismo número de teléfono del destinatario en un periodo breve de tiempo. | Espera y vuelve a realizar la operación si pretendes enviar mensajes al mismo número de teléfono. No obstante, puedes enviar mensajes a un número de teléfono diferente sin tener que esperar. |
Solicitud incorrecta |
Se ha superado el límite de frecuencia de cancelación del registro de la cuenta | Se ha producido un error durante el registro o la cancelación del registro debido a demasiados intentos de este número de teléfono en un breve periodo de tiempo. | El número de teléfono de empresa se va a bloquear porque ha alcanzado el límite de intentos de registro o cancelación de registro. Inténtalo de nuevo una vez que el número esté desbloqueado. Consulta “Limitaciones” en el documento Registro. |
Solicitud incorrecta |
Código | Descripción | Posibles soluciones | Código de estado HTTP |
---|---|---|---|
Bloqueada temporalmente por incumplimiento de las políticas | La cuenta de WhatsApp Business asociada a la aplicación se ha restringido o desactivado por incumplir una política de la plataforma. | Consulta el documento sobre la aplicación de las políticas para obtener información sobre las infracciones de las políticas y cómo resolverlas. |
Prohibido |
Se ha restringido la capacidad de la cuenta empresarial para enviar mensajes a los usuario en este país. | Se ha restringido la capacidad de la cuenta de WhatsApp Business para enviar mensajes a usuarios en determinados países. | Consulta la Política de mensajes de WhatsApp Business para obtener más información sobre los países a los que se puede enviar mensajes con tu categoría de empresa. |
Prohibido |
La cuenta se ha bloqueado | La cuenta de WhatsApp Business asociada a la aplicación se ha restringido o desactivado por incumplir una política de la plataforma o no se han podido verificar los datos incluidos en la solicitud según los datos definidos en la cuenta de WhatsApp Business (p. ej., el PIN de la verificación en dos pasos incluido en la solicitud es incorrecto). | Consulta el documento sobre el cumplimiento de la política para obtener información sobre las infracciones de las políticas y cómo resolverlas. También puedes usar la API de estado, que puede proporcionar insights adicionales sobre el motivo o motivos 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. | En la página Estado de la Plataforma de WhatsApp Business puedes consultar información sobre el estado de la API. Si no hay cortes del servidor, consulta la referencia del extremo y verifica que el formato de la solicitud sea el correcto y cumpla con todos los requisitos del extremo. |
Solicitud incorrecta |
Servicio de API | Error temporal por tiempo de inactividad o sobrecarga. | En la página Estado de la Plataforma de WhatsApp Business puedes consultar información sobre el estado del a API antes de volver a intentarlo. |
Servicio no disponible |
El valor del parámetro no es válido | El número de teléfono de empresa se ha eliminado. | Verifica que el número de teléfono de empresa sea correcto. |
Solicitud incorrecta |
Parámetro no válido | La solicitud incluía uno o varios parámetros mal escritos o no admitidos. | Consulta la referencia del extremo para determinar qué parámetros se admiten y cómo se escriben. Al establecer la clave pública de la empresa, asegúrate de que sea una clave pública RSA válida de 2048 bits en formato PEM. Asegúrate de que no haya discrepancias entre el identificador del número de teléfono que vas a registrar y un identificador de número de teléfono almacenado previamente. Asegúrate de que el parámetro no tiene restricciones de longitud para el tipo. |
Solicitud incorrecta |
El número del usuario forma parte de un experimento | El mensaje no se ha enviado como parte de un experimento. | Consulta Experimento de mensajes de marketing. |
Solicitud incorrecta |
Se ha producido un error | El mensaje no se pudo enviar debido a un error desconocido. Al establecer la clave pública de una empresa, no se pudo calcular la firma, no se pudo llamar al extremo de GraphQL o el extremo de GraphQL devolvió un error. | Vuelve a intentarlo. Si el error continúa, abre una solicitud de asistencia directa. |
Error interno del servidor |
Acceso denegado | No se ha concedido un permiso o se ha eliminado. | Utiliza el depurador de identificadores de acceso para verificar que los permisos que necesita el extremo se hayan concedido a la aplicación. Consulta Solucionar problemas. |
Prohibido |
Falta un parámetro necesario | Falta un parámetro necesario en la solicitud. | Consulta la referencia del extremo para determinar qué parámetros son necesarios. |
Solicitud incorrecta |
El valor del parámetro no es válido | El valor de uno o varios de los parámetros no es válido. | Consulta la referencia del extremo para determinar los valores que se admiten para cada parámetro. Para obtener información sobre cómo añadir un número de teléfono a una cuenta de WhatsApp Business, consulta Números de teléfono. |
Solicitud incorrecta |
Servicio no disponible | Un servicio no está disponible temporalmente. | En la página Estado de la Plataforma de WhatsApp Business puedes consultar información sobre el estado de la API antes de volver a intentarlo. |
Error interno del servidor |
El destinatario no puede ser el remitente | El número de teléfono del destinatario y del remitente es el mismo. | Envía un mensaje a un número de teléfono distinto al del remitente. |
Solicitud incorrecta |
El mensaje no se puede entregar | No se puede entregar el mensaje. Los motivos pueden ser algunos de los siguientes:
| Con un método de comunicación que no sea de WhatsApp, pide al usuario de WhatsApp lo siguiente:
|
Solicitud incorrecta |
Problema de pago relacionado con la idoneidad de la empresa | Se ha producido un error relacionado con el método de pago. | Consulta Información sobre la facturación de tu cuenta de WhatsApp Business y verifica que hayas configurado la facturación correctamente. Problemas habituales:
|
Solicitud incorrecta |
Certificado incorrecto | El mensaje no se pudo enviar 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 interno del servidor |
Mensaje de reactivación | Han transcurrido más de 24 horas desde que el destinatario respondió por última vez al número del remitente. | Envía un mensaje iniciado por la empresa al destinatario mediante una plantilla de mensaje. |
Solicitud incorrecta |
Meta ha decidido no entregarlo. | Este mensaje no se ha entregado para mantener una buena interacción en el ecosistema. | No vuelvas a intentarlo inmediatamente si recibes este código de error y sospechas que se debe al límite. En lugar de eso, vuelve a intentar aumentar los incrementos de tiempo más largos hasta que el mensaje se entregue, ya que el límite puede estar vigente durante diferentes periodos de tiempo. Consulta Límites de mensajes de plantilla de marketing por usuario para obtener más información. |
Solicitud incorrecta |
Tipo de mensaje no admitido | No se admite el tipo de mensaje. | En Mensajes, puedes consultar los tipos de mensajes admitidos antes de volver a intentarlo con uno admitido. |
Solicitud incorrecta |
Error de descarga de contenido multimedia | No se puede descargar el contenido multimedia que ha enviado el usuario. | No hemos podido descargar el contenido multimedia incluido en el mensaje del usuario de WhatsApp. Para obtener más información, consulta el valor de Pide al usuario de WhatsApp que te envíe el archivo multimedia con un método que no sea de WhatsApp. |
Solicitud incorrecta |
Error de subida de contenido multimedia | No se puede subir el contenido multimedia utilizado en el mensaje. | No hemos podido subir el contenido multimedia debido a uno o varios motivos, como un tipo de contenido multimedia no admitido. Para obtener más información, consulta el valor de Te recomendamos que revises los archivos multimedia que estén provocando errores y confirmes que efectivamente se admiten. Por ejemplo, en UNIX puedes utilizar la inspección de archivos mediante la línea de comandos para determinar el tipo MIME correspondiente:
Después, puedes confirmar si el tipo MIME se admite. Consulta Tipos de contenido multimedia admitidos. |
Solicitud incorrecta |
Cuenta en modo de mantenimiento | La cuenta empresarial está en modo de mantenimiento. | La cuenta de WhatsApp Business está en modo de mantenimiento. Uno de los motivos podría ser que la cuenta se está sometiendo a una actualización de rendimiento. |
Solicitud incorrecta |
Error de coincidencia del recuento de parámetros de la plantilla | El número de valores de parámetros de variable incluidos en la solicitud no coincidía con el número de parámetros de variable definidos en la plantilla. | Consulta Normas para plantillas de mensajes y asegúrate de que la solicitud incluya todos los valores de parámetros de variable que se han definido en la plantilla. |
Solicitud incorrecta |
La plantilla no existe | La plantilla no existe en el idioma especificado o no se ha aprobado. | Asegúrate de que la plantilla se haya aprobado y de que la configuración regional de idioma y el nombre sean correctos. Asegúrate de seguir las normas para plantillas de mensajes. |
No se ha podido encontrar |
El texto hidratado de la plantilla es demasiado largo | El texto traducido es demasiado largo. | Consulta el Administrador de WhatsApp para verificar 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 la plantilla | El contenido de la plantilla infringe una política de WhatsApp. | Consulta Motivos de rechazo para determinar los posibles motivos de la infracción. |
Solicitud incorrecta |
Error de coincidencia del formato del parámetro de la plantilla | Los valores de parámetros de variable tienen un formato incorrecto. | Los valores de parámetros de variable incluidos en la solicitud no usan el formato indicado en la plantilla. Consulta Normas para plantillas de mensajes. |
Solicitud incorrecta |
La plantilla está en pausa | La plantilla está en pausa por baja calidad, por lo que no se puede enviar en un mensaje de plantilla. | Edita la plantilla para mejorar la calidad y vuelve a intentarlo una vez que se haya aprobado. |
Solicitud incorrecta |
La plantilla está desactivada | La plantilla se ha pausado demasiadas veces debido a su baja calidad y se ha desactivado permanentemente. | Crea una nueva plantilla con un contenido diferente. |
Solicitud incorrecta |
El proceso está bloqueado | El proceso se encuentra en un estado bloqueado. | Corrige el proceso. |
Solicitud incorrecta |
El proceso está limitado | El proceso se encuentra en un estado limitado y ya se han enviado diez mensajes con dicho proceso en la última hora. | Corrige el proceso. |
Solicitud incorrecta |
Cancelación incompleta del registro | Se ha producido un error en un intento anterior de cancelación del registro. | Vuelve a cancelar el registro del número antes de registrarlo. |
Error interno del servidor |
Servidor no disponible temporalmente | El servidor no está disponible temporalmente. | En la página Estado de la Plataforma de WhatsApp Business puedes consultar información sobre el estado de la API y comprobar el valor de |
Servicio no disponible |
Error de coincidencia del 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 el correcto. Para restablecer el PIN de verificación en dos pasos, sigue estas indicaciones:
|
Solicitud incorrecta |
Es necesario volver a verificar el número de teléfono | Hay que verificar el número de teléfono antes de registrarlo. | Verifica el número de teléfono antes de registrarlo. |
Solicitud incorrecta |
Demasiados intentos de averiguar el PIN de verificación en dos pasos | Se ha intentado averiguar demasiadas veces el PIN de verificación en dos pasos de este número de teléfono. | Vuelve a intentarlo una vez transcurrido el periodo de tiempo indicado en el valor de la respuesta de |
Solicitud incorrecta |
El PIN de verificación en dos pasos se ha intentado averiguar demasiado rápido | El PIN de verificación en dos pasos se ha introducido demasiado rápido. | Comprueba el valor de la respuesta de |
Solicitud incorrecta |
Número de teléfono no registrado | El número de teléfono no está registrado en la Plataforma de WhatsApp Business. | Registra el número de teléfono antes de volver a intentarlo. |
Solicitud incorrecta |
Espera unos minutos antes de intentar registrar este número de teléfono | El número de teléfono que intentas registrar se ha eliminado recientemente y la eliminación todavía no se ha completado. | Espera cinco minutos antes de volver a intentar la solicitud. |
Solicitud incorrecta |
Error genérico de usuario | El mensaje no se pudo enviar debido a un error desconocido en los parámetros de la solicitud. | Consulta la referencia del extremo para determinar si estás consultando el extremo con la sintaxis correcta. Ponte en contacto con el servicio de atención al cliente si sigues recibiendo este código de error en la respuesta. |
Solicitud incorrecta |