Los códigos de error de Meta, traducidos

Si tu negocio manda mensajes desde un sistema propio, esta nota traduce los errores que devuelve Meta y dice qué hacer con cada uno. Los envíos salen por la API de Meta, la puerta por la que un programa le entrega mensajes a WhatsApp, Messenger o Instagram.

Cuando un envío falla, la respuesta trae un código numérico, a veces un subcódigo, y un mensaje en inglés escrito para el programador. Ninguna de las tres cosas le sirve a quien está atendiendo la bandeja. Esa persona necesita saber una sola cosa: si el problema es de este mensaje, de este cliente o de toda la conexión.

Meta reparte la documentación de sus códigos en tres sitios: la referencia de WhatsApp Cloud API, la de Messenger Platform y la general de Graph API. En inglés, y sin decir qué hacer con cada uno. Lo que sigue es la tabla que armamos nosotros, un error a la vez, y la regla de decisión que va con ella.

El que más se ve es el 131047. No es culpa de nadie: es la regla de las 24 horas cumpliéndose. Tratarlo como un fallo asusta al equipo sin motivo. Lo correcto es ofrecerle a quien atiende la plantilla que sí puede mandar.

Los tres últimos son comunes a los tres canales. El token que aparece en la tabla es la llave con la que Meta reconoce al sistema que envía.

El 190 y el 200 son los únicos que justifican apagar una bandeja entera. Sin llave o sin permisos no va a salir nada más, y seguir intentando solo llena el registro de fallos.

El código 10 es la trampa. A secas significa que la aplicación no tiene permiso, y la reacción correcta es apagar la bandeja. Pero ese mismo 10 con el subcódigo 2018278 dice otra cosa. Dice que en Messenger pasaron las 24 horas desde el último mensaje de la persona, que es una situación normal y esperada.

Si el código se lee sin mirar el subcódigo, un cliente que tardó un día en contestar apaga la bandeja completa de un negocio.

Primero se mira el subcódigo, y solo después el código. Al revés, el error más común de Messenger se confunde con el más grave.

El tiempo de espera agotado no es un rechazo. Si la petición a Meta expira sin respuesta, el mensaje puede haber salido igual. Reintentar a ciegas es la forma más rápida de mandarle dos veces lo mismo a un cliente.

Nosotros lo marcamos como «incierto» y lo dejamos encolado con su reserva puesta. Solo se reintenta cuando esa reserva expira sola, dos minutos después. El plazo de espera normal es de 10 segundos; para subir o bajar archivos, 60.

Un 200 sin identificador es un error. El 200 significa que Meta recibió el envío, pero a veces lo responde sin devolver el id del mensaje. Guardarlo como enviado dejaría un mensaje imposible de rastrear: no llegará su acuse de entrega ni el de lectura. Se trata como fallo, con su texto: «Meta aceptó el envío pero no devolvió identificador».

De esas dos situaciones sale una regla de arquitectura. La capa que habla con Meta nunca corta el programa con una excepción. Devuelve un resultado normal, con el error dentro. Un envío que falla no es un error del programa; es un hecho del negocio, y se registra como tal.

• Traduce cada código a una de tres preguntas: ¿es de este mensaje, de este contacto o de la conexión? Solo la tercera apaga algo.
• Lee el subcódigo antes que el código. Siempre.
• Guarda el mensaje original de Meta junto a la traducción. Cuando la tabla no alcance, es lo que hay que buscar en su documentación.
• Fija la versión de la API en una variable de entorno, no dentro del código. Meta jubila cada versión a los dos años, y una versión escrita en el código convierte esa jubilación en una caída el día que toque.