Ir al contenido
Boost

Canales: envío directo a Meta y SES

Códigos de error · 78 códigos · 2 por retirar · catálogo del 2026-10-21

Todo mensaje que sale a WhatsApp, Messenger, Instagram o correo pasa por ChannelSendService (src/channels/send/). Cada error es un ChannelSendError con code, reason_code, retry_after_seconds y retry_at.

Para toda la familia

Lo que un código no dice lo hereda de aquí.

Cómo se detecta
Respuesta del envío (code + reason_code). Mensaje fallido: channel_messages.status = 'failed' con error_code / error_json. Render: channel_send_rejected, channel_send_unknown_delivery, channel_send_prepare_failed.
Qué hacer
Guíate por el reason_code (ver la familia «Motivos de envío»): plantilla si la ventana está cerrada, esperar si es límite, reconectar si la cuenta no puede enviar, corregir el mensaje si está mal armado.
78 códigos

Códigos

CHANNEL_SEND_ACTOR_REQUIRED

HTTPHTTP 400

Un envío de automatización necesita workflow_id y execution_id (o, desde el camino de hoy, su usuario y service_kind).

CHANNEL_SEND_CONTACT_RATE_LIMITED

HTTPHTTP 429

Tope de envíos automáticos a un mismo contacto (429). Solo corta con CHANNELS_SEND_CONTACT_CAP_MODE=enforce; en modo observar el mensaje sale.

CHANNEL_SEND_FAILED

detalleHTTPHTTP 400HTTP 429HTTP 502

El envío falló. El reason_code y el title dicen por qué (límite de Meta, rechazo, mensaje mal armado); también lo devuelve un reintento con un client_message_id que ya había fallado.

Cómo detectarlo
Base: channel_messages.status = 'failed' con error_code y error_json. Render: channel_send_rejected … meta=<n>.

CHANNEL_SEND_FIELD_INVALID

HTTPHTTP 400

Un campo del mensaje tiene un valor inválido para el canal (p. ej. un botón con URL que no es https). El title dice cuál.

CHANNEL_SEND_FIELD_REQUIRED

HTTPHTTP 400

Falta un campo obligatorio del mensaje (p. ej. la reacción sin el mensaje al que responde). El title dice cuál.

CHANNEL_SEND_IN_FLIGHT

detalle

Hay un envío en curso (o sin respuesta de Meta) con este client_message_id; no se reenvía.

CHANNEL_SEND_INSTAGRAM_FILE_UNSUPPORTED

HTTPHTTP 400

Se intentó mandar por Instagram un archivo que no es PDF (Word, Excel, zip…). Instagram solo acepta PDF como archivo (además de imagen, video y audio); el envío se niega antes de registrar nada.

Causa típica
Desde el chat: se adjuntó un documento con el compositor en Instagram. Desde un workflow: comms.send_document por Instagram con un archivo que no es PDF.
Qué hacer
Mandar el documento como PDF, o por WhatsApp, Messenger o correo, que sí lo aceptan.

CHANNEL_SEND_LIMITS_EXCEEDED

HTTPHTTP 400

El mensaje pasa un límite del canal (largo del texto, cantidad de botones, filas o adjuntos). El title dice cuál.

CHANNEL_SEND_PROVIDER_RATE_LIMITED

detalleHTTPHTTP 429

Meta está limitando los envíos de esta cuenta (número, página o WABA). Reintentar antes del tiempo que dice Meta no adelanta nada.

Qué hacer
Esperar retry_after_seconds (o retry_at); si viene en null, Meta no dijo cuánto y Boost no lo inventa.

CHANNEL_SEND_THREAD_NOT_FOUND

HTTPHTTP 404

No hay un hilo de esta cuenta para ese chat en Messenger/Instagram. La salida directa no crea hilos: solo responde en uno que ya existe. Si la conversación lleva el hilo de otra cuenta (el chat único del contacto suele llevar el de WhatsApp), antes de fallar busca el de esta página por la ruta activa del contacto y por la identidad (PSID/IGSID) del destinatario.

Causa típica
El contacto no tiene ni ruta ni identidad con hilo en esta página: nunca le escribió a esta cuenta en Boost (la conversación empezó por otro canal o por otra página), o no tiene su id de Messenger/Instagram.
Qué hacer
Esperar a que el cliente escriba primero por esa página; no se puede iniciar un chat de Messenger/Instagram desde Boost.

CHANNEL_SEND_TOKEN_UNAVAILABLE

HTTPHTTP 409

No se pudo obtener el token de la cuenta desde la bóveda; el mensaje dice el VAULT_* que respondió.

Qué hacer
Si es VAULT_SECRET_NOT_FOUND o VAULT_SECRET_EXPIRED, reconectar la cuenta del canal.

CHANNEL_SEND_UNKNOWN_DELIVERY

detalleHTTPHTTP 504

Meta no respondió a tiempo y no se sabe si el mensaje salió (504). No se reintenta solo para no duplicar.

CHANNEL_TEMPLATES_RATE_LIMITED

HTTPHTTP 429

Meta está limitando las consultas de plantillas de esta cuenta de WhatsApp. Reintentar antes no adelanta la recuperación.

EMAIL_AUTOMATED_THREAD_LIMIT

HTTPHTTP 429

Tope de correos automáticos por hilo: una automatización (workflow o copiloto) ya mandó CHANNELS_EMAIL_AUTOMATED_PER_THREAD_24H correos (3 por defecto) a ese hilo en 24 h y el siguiente no sale (429, reason_code CONTACT_RATE_LIMITED, retry_after_seconds = cuándo vence el más viejo). No se persiste nada ni se llama a SES. Una persona nunca cuenta ni se frena.

Cómo detectarlo
Respuesta (code). La negación queda en authz_decisions (allowed = 0, reason_code = 'CONTACT_RATE_LIMITED', detail.limit_key = 'email_thread_24h').
Qué hacer
No reintentes antes de retry_after_seconds: es el candado contra bucles de correo, no una falla. Si el tope es corto para un caso legítimo, se ajusta con la variable, no con código.

EMAIL_PROVIDER_REJECTED

HTTPHTTP 400HTTP 502

SES rechazó el correo.

Causa típica
Dirección de destino inválida, contenido rechazado, o el buzón o el dominio no pueden enviar en SES.
Cómo detectarlo
Respuesta del envío (400 si es del mensaje, 502 si es de SES). Render: líneas del adaptador de SES.
Qué hacer
Revisar la dirección y el contenido. Si pasa con todos los correos del buzón, revisar el dominio y el buzón en Configuración → Canales.

WHATSAPP_SESSION_EXPIRED

detalleHTTPHTTP 400

La ventana de 24 h de WhatsApp está cerrada (o nunca se abrió): solo se puede enviar una plantilla aprobada.

Causa típica
El cliente no escribió en las últimas 24 h, o ese número todavía no tiene conversación con el contacto.
Cómo detectarlo
Respuesta 400 con reason_code: WINDOW_CLOSED. Con outside_window = skip no es error: el envío se omite y viene como error del resultado.
Qué hacer
Mandar una plantilla preaprobada; cuando el cliente responda, se abre la ventana.

Por retirar

Todavía existen, pero van a desaparecer junto con el camino que los produce. No los uses en código nuevo.

CHANNEL_SEND_EGRESS_NOT_BOOST

HTTPHTTP 409por retirar

La cuenta no sale por Boost (egress_owner distinto de boost): la salida directa no la toca y no tiene otro camino. Hay que pasarla a Boost.

Por retirar
Muere con los interruptores por cuenta.

CHANNEL_SEND_LEGACY_ROUTE_REQUIRED

HTTPHTTP 400por retirar

La cuenta no está en ingreso boost: el chat, el destinatario y la ventana tienen que venir del camino viejo y no vinieron.

Por retirar
Todavía existe, pero va a desaparecer junto con el camino que lo produce. No lo uses en código nuevo.

Texto generado desde el catálogo de errores de BoostAPI. Para corregirlo, se cambia allá y se sincroniza: verMantener esta documentación. También enMarkdown.