Códigos de error de la API de nube

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.

Recepción de errores: síncronos y asíncronos

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.

Webhooks y sintaxis de la respuesta de error

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

Contenido de la respuesta de error

Propiedad Tipo de valor Descripción

code

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.

details

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.

error_subcode

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

fbtrace_id

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.

message

Cadena

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

messaging_product

Cadena

Producto de mensajes. En el caso de las respuestas de la API de nube, siempre será la cadena whatsapp.

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

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.

401

No autorizado

3

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.

500

Error interno del servidor

10

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.

403

Prohibido

190

El identificador de acceso ha caducado

El identificador de acceso ha caducado.

Obtén un nuevo identificador de acceso.

401

No autorizado

200-299

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.

403

Prohibido

Errores de restricción

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

4

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.

400

Solicitud incorrecta

80007

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.

400

Solicitud incorrecta

130429

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.

400

Solicitud incorrecta

131048

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.

400

Solicitud incorrecta

131056

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.

400

Solicitud incorrecta

133016

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.

400

Solicitud incorrecta

Errores de integridad

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

368

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.

403

Prohibido

130497

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.

403

Prohibido

131031

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.

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.

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.

400

Solicitud incorrecta

2

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.

503

Servicio no disponible

33

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.

400

Solicitud incorrecta

100

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.

400

Solicitud incorrecta

130472

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.

400

Solicitud incorrecta

131000

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.

500

Error interno del servidor

131005

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.

403

Prohibido

131008

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.

400

Solicitud incorrecta

131009

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.

400

Solicitud incorrecta

131016

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.

500

Error interno del servidor

131021

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.

400

Solicitud incorrecta

131026

El mensaje no se puede entregar

No se puede entregar el mensaje. Los motivos pueden ser algunos de los siguientes:

  • El número de teléfono del destinatario no es un número de teléfono de WhatsApp.
  • Se envía un plantilla de autenticación a un usuario de WhatsApp con el código de llamada de país +91 (India). En este momento las plantillas de autenticación no se pueden enviar a los usuarios de WhatsApp de la India.
  • El destinatario no ha aceptado nuestras nuevas Condiciones del servicio y Política de privacidad.
  • El destinatario utiliza 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

Con un método de comunicación que no sea de WhatsApp, pide al usuario de WhatsApp lo siguiente:

  • Debe confirmar que realmente puede enviar un mensaje a tu número de teléfono de empresa de WhatsApp.
  • Debe confirmar que ha aceptado nuestras Condiciones del servicio más recientes (en Configuración > Ayuda o Configuración > Información de la aplicación, tendrá que aceptar las condiciones o políticas más recientes si todavía no lo ha hecho).
  • Debe actualizar a la versión más reciente del cliente de WhatsApp.

400

Solicitud incorrecta

131042

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:

  • La cuenta de pago no está vinculada a ninguna cuenta de WhatsApp Business.
  • La línea de crédito es superior al límite.
  • La línea de crédito (cuenta de pago) no está establecida o no está activa.
  • La cuenta de WhatsApp Business se ha eliminado.
  • La cuenta de WhatsApp Business se ha suspendido.
  • La zona horaria no está establecida.
  • La divisa no está establecida.
  • La solicitud MessagingFor (en nombre de) está pendiente o se ha rechazado.
  • Se ha superado el umbral de nivel gratuito de conversación sin un método de pago válido.

400

Solicitud incorrecta

131045

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.

500

Error interno del servidor

131047

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.

400

Solicitud incorrecta

131049

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.

400

Solicitud incorrecta

131051

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.

400

Solicitud incorrecta

131052

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 error.error_data.details en los webhooks de mensajes activados al recibir este mensaje.

Pide al usuario de WhatsApp que te envíe el archivo multimedia con un método que no sea de WhatsApp.

400

Solicitud incorrecta

131053

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 error.error_data.details en los webhooks de mensajes activados al no poder enviar el mensaje.

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:

file -I rejected-file.mov

Después, puedes confirmar si el tipo MIME se admite. Consulta Tipos de contenido multimedia admitidos.

400

Solicitud incorrecta

131057

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.

500

Solicitud incorrecta

132000

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.

400

Solicitud incorrecta

132001

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.

404

No se ha podido encontrar

132005

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.

400

Solicitud incorrecta

132007

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.

400

Solicitud incorrecta

132012

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.

400

Solicitud incorrecta

132015

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.

400

Solicitud incorrecta

132016

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.

400

Solicitud incorrecta

132068

El proceso está bloqueado

El proceso se encuentra en un estado bloqueado.

Corrige el proceso.

400

Solicitud incorrecta

132069

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.

400

Solicitud incorrecta

133000

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.

500

Error interno del servidor

133004

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

503

Servicio no disponible

133005

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:


  1. Inhabilita la verificación en dos pasos.
  2. Envía una solicitud POST en la que se incluya el nuevo PIN al extremo de números de teléfono.

400

Solicitud incorrecta

133006

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.

400

Solicitud incorrecta

133008

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

400

Solicitud incorrecta

133009

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

400

Solicitud incorrecta

133010

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.

400

Solicitud incorrecta

133015

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.

400

Solicitud incorrecta

135000

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.

400

Solicitud incorrecta