Códigos de error de la API de la nube

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.

Recibir errores: método sincrónico y asincrónico

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.

Webhooks y sintaxis de respuesta de error

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>"
  }
}

Contenido de la respuesta de error

Propiedad Tipo de valor Descripción

code

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.

details

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.

error_subcode

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 code y details.

fbtrace_id

Cadena

Identificador de seguimiento que puedes incluir cuando te comunicas con la asistencia directa. El identificador puede ayudarnos a depurar el error.

message

Cadena

Combinación del código de error y su título. Por ejemplo: (#130429) Rate limit hit.

messaging_product

Cadena

Productos de mensajes. Será siempre la cadena whatsapp en las respuestas de la API de la nube.

type

Cadena

Tipo de error.

Ejemplo de respuesta:

{
  "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ódigos de error

Errores de autorización

Código Descripción Posibles soluciones Código de estado HTTP

0

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.

401

No autorizado

3

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.

500

Error de servidor interno

10

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.

403

Prohibido

190

El token de acceso caducó

El token de acceso caducó.

Obtén un nuevo token de acceso.

401

No autorizado

200-299

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.

403

Prohibido

Errores de limitación

Código Descripción Posibles soluciones Código de estado HTTP

4

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.

400

Solicitud incorrecta

80007

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.

400

Solicitud incorrecta

130429

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.

400

Solicitud incorrecta

131048

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.

400

Solicitud incorrecta

131056

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.

400

Solicitud incorrecta

133016

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.

400

Solicitud incorrecta

Errores de integración

Código Descripción Posibles soluciones Código de estado HTTP

368

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.

403

Prohibido

130497

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.

403

Prohibido

131031

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.

403

Prohibido

Otros errores

Código Descripción Posibles soluciones Código de estado HTTP

1

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.

400

Solicitud incorrecta

2

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.

503

Servicio no disponible

33

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.

400

Solicitud incorrecta

100

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.

400

Solicitud incorrecta

130472

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.

400

Solicitud incorrecta

131000

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.

500

Error de servidor interno

131005

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.

403

Prohibido

131008

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.

400

Solicitud incorrecta

131009

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.

400

Solicitud incorrecta

131016

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.

500

Error de servidor interno

131021

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.

400

Solicitud incorrecta

131026

El mensaje no se puede enviar

No se puede enviar el mensaje. Entre las posibles razones, se incluyen las siguientes:

  • El número de teléfono del destinatario no es un número de teléfono de WhatsApp.
  • Enviar una plantilla de autenticación a un usuario de WhatsApp que tiene un código de llamada de país +91 (India). Actualmente, no se puede enviar plantillas de autenticación a usuarios de WhatsApp de India.
  • El destinatario no aceptó las nuevas Condiciones del servicio y Política de privacidad.
  • El destinatario usa una versión antigua de WhatsApp. Debe usar la siguiente versión de WhatsApp o una posterior:
    • Android: 2.21.15.15
    • SMBA: 2.21.15.15
    • iOS: 2.21.170.4
    • SMBI: 2.21.170.4
    • KaiOS: 2.2130.10
    • Web: 2.2132.6

Utiliza un método de comunicación que no sea WhatsApp y pídele al usuario de WhatsApp que realice lo siguiente:

  • Confirme que puede enviar un mensaje a tu número de teléfono comercial de WhatsApp.
  • Confirme que aceptó nuestras Condiciones del servicio más recientes (si va a Configuración > Ayuda, o Configuración > Información de la aplicación se le pedirá que acepte las condiciones y políticas más recientes, si aún no lo hizo).
  • Actualice a la última versión del cliente de WhatsApp

400

Solicitud incorrecta

131042

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:

  • La cuenta de pago no está anexada a una cuenta de WhatsApp Business.
  • La línea de crédito superó el límite.
  • No se configuró o no se activó la línea de crédito (cuenta de pago).
  • Se eliminó la cuenta de WhatsApp Business.
  • Se suspendió la cuenta de WhatsApp Business.
  • No se configuró la zona horaria.
  • No se configuró la divisa.
  • La solicitud de MessagingFor ("en nombre de") está pendiente o se rechazó.
  • Se superó el límite de niveles gratuitos de conversación sin contar con un método de pago válido.

400

Solicitud incorrecta

131045

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.

500

Error de servidor interno

131047

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.

400

Solicitud incorrecta

131049

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.

400

Solicitud incorrecta

131051

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.

400

Solicitud incorrecta

131052

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 error.error_data.details en los webhooks de los mensajes que se activan cuando se recibe este mensaje.

Pídele al usuario de WhatsApp que te envíe el archivo multimedia por un canal diferente a WhatsApp.

400

Solicitud incorrecta

131053

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 error.error_data.details en los webhooks de los mensajes que se activan cuando no se envía este mensaje.

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:

file -I rejected-file.mov

Luego, puedes confirmar si se admite el tipo MIME. Consulta los tipos de archivos multimedia compatibles.

400

Solicitud incorrecta

131057

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.

500

Solicitud incorrecta

132000

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.

400

Solicitud incorrecta

132001

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.

404

No se encontró

132005

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.

400

Solicitud incorrecta

132007

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.

400

Solicitud incorrecta

132012

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.

400

Solicitud incorrecta

132015

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.

400

Solicitud incorrecta

132016

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.

400

Solicitud incorrecta

132068

Proceso bloqueado

El proceso se encuentra en estado bloqueado.

Corrige el proceso.

400

Solicitud incorrecta

132069

Proceso limitado

El proceso está limitado, y en la última hora ya se enviaron 10 mensajes que usan este proceso.

Corregir el proceso

400

Solicitud incorrecta

133000

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.

500

Error de servidor interno

133004

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 details antes de volver a intentarlo.

503

Servicio no disponible

133005

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:


  1. Desactiva la autorización en dos pasos.
  2. Envía una solicitud POST que incluya el nuevo PIN al punto de conexión del número de teléfono.

400

Solicitud incorrecta

133006

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.

400

Solicitud incorrecta

133008

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 details.

400

Solicitud incorrecta

133009

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 details para volver a intentarlo.

400

Solicitud incorrecta

133010

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.

400

Solicitud incorrecta

133015

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.

400

Solicitud incorrecta

135000

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.

400

Solicitud incorrecta