Códigos de error
Cada error que el backend de Boost devuelve o registra a propósito lleva un código estable: un nombre corto como CONTACT_INACTIVE o agenda_seller_missing que no cambia aunque cambie el texto del mensaje. Con el código se encuentra aquí qué significa, la causa típica, cómo detectarlo y qué hacer.
Esta sección no se escribe a mano: sale del catálogo de errores del backend, que se arma leyendo el código, y se copia aquí con una sincronización (ver cómo se mantiene). Cada código tiene su ficha dentro de la página de su familia.
Buscar un código
Sección titulada «Buscar un código»849 códigos. Escribe para buscar.
- Respeta mayúsculas.
ROLE_NOT_FOUNDyrole_not_foundson dos códigos distintos, de familias distintas. - Enlace directo. Cada ficha tiene un ancla con el código exacto: la página de su familia seguida de
#CODIGO(por ejemplo,/codigos-de-error/cartera/#CONTACT_INACTIVE). Ese enlace es estable: sirve para un ticket o una revisión de código. - Buscador del sitio. El de arriba a la derecha (Ctrl + K, o ⌘ + K) también encuentra los códigos y lleva a su ficha. Cada página de familia, además, tiene su propio filtro.
Dónde aparece un código
Sección titulada «Dónde aparece un código»- En la respuesta HTTP del backend: el campo
codedel cuerpo. Si la petición pasó por la web (el BFF), el código sube comocodey el cuerpo original queda completo endetails; algunas rutas del BFF solo lo dejan endetails.code. En el navegador: herramientas de desarrollo → Red → la petición que falló → Respuesta. - En los registros del servidor: líneas escritas a propósito con
code=…,cause=…oreason=…(cada familia dice cuál buscar). - En una tabla: el código de error de un mensaje fallido, la causa en el registro de una ejecución de workflow o la decisión del webhook de pagos.
Cómo viene en una respuesta HTTP
Sección titulada «Cómo viene en una respuesta HTTP»El backend responde el cuerpo que armó la excepción, tal cual. Hay cuatro formas:
| Forma | Cuerpo | Cuándo |
|---|---|---|
| Con código | { code, message, …datos } |
La mayoría de los errores de negocio: el code está en el catálogo y message es un texto en español para la persona. |
| Operación | { code, message, recoverable, retryable, errors: [{ field, code, message, line_index, … }], side_effects } |
Cotizaciones, órdenes y oportunidades. errors[] trae un renglón por campo o línea con problema; side_effects dice qué ya se hizo en Zauru, así que no se repite a ciegas. |
| Envío por canal | { code, message, reason_code, retry_after_seconds, retry_at, … } |
Envíos por WhatsApp, Messenger, Instagram o correo. reason_code es la clase del fallo; retry_after_seconds es el que dio Meta, o null: Boost no inventa esperas. |
| Sin código | { statusCode, message, error } |
Una excepción que solo lleva texto, o un error 500 no atrapado. No está en el catálogo. |
Un ejemplo de la primera forma, con status 409:
{ "code": "CONTACT_INACTIVE", "message": "<texto en español para la persona>"}Y lo que recibe el navegador cuando la misma respuesta pasa por el BFF, con el mismo status:
{ "error": "boost_api_error", "code": "CONTACT_INACTIVE", "message": "<el mismo texto>", "details": { "code": "CONTACT_INACTIVE", "message": "<el mismo texto>" }}La pantalla casi nunca muestra el código: traduce algunos a un texto propio (envío del chat, cotizaciones y órdenes, catálogo, inicio de sesión) y, si no lo conoce, muestra el message del backend o un texto genérico. Para reportar un error de pantalla, lo útil es el código y la hora.
Tipos de código
Sección titulada «Tipos de código»Un código puede aparecer de más de una forma; su ficha dice cuál.
| Tipo | Qué es |
|---|---|
| HTTP | El code del cuerpo de una respuesta de error. |
| detalle | Viene dentro de una respuesta: un renglón de errors[] o el code de un resultado que no es excepción ({ ok: false, code }). |
| interno | Un error tipado con código estable dentro del backend. Quien lo atrapa lo traduce a una respuesta, o termina en un registro o en una tabla. |
| workflow | La causa de un fallo al ejecutar un workflow: queda en el registro de la ejecución. |
| alarma | Una alarma del vigía de canales, que revisa cada pocos minutos la recepción y el envío de mensajes. Trae severidad. |
| sesión | El veredicto de la revisión de sesión: el que no deja pasar responde 401. |
| motivo | El reason_code de un envío por canal: la clase del fallo, junto al code concreto. |
| pago | La decisión del webhook de pagos sobre un aviso de pago. |
| Meta | Un código numérico de la Graph API de Meta que Boost reconoce y explica. |
Estados
Sección titulada «Estados»| Estado | Qué quiere decir |
|---|---|
| vigente | El backend lo puede devolver hoy. |
| por retirar | Todavía existe, pero va a desaparecer junto con el camino que lo produce. No se usa en código nuevo. Aparece al final de su familia, atenuado. |
| retirado | El backend ya no lo devuelve. Se conserva, con su fecha, para reconocerlo en registros viejos. Están juntos en Retirados. |
Familias
Sección titulada «Familias»Cada familia agrupa los códigos de un área y trae cómo se detectan y qué hacer en general; un código hereda de su familia lo que su ficha no dice.
793 vigentes, 13 por retirar y 43 retirados.
Códigos que se arman al vuelo
Sección titulada «Códigos que se arman al vuelo»Algunos códigos se componen en tiempo de ejecución, así que el catálogo los lista como patrón y no uno por uno:
CHANNEL_SEND_META_*HTTP_*MEDIA_DOWNLOAD_*MEDIA_LOOKUP_*
Los de Meta más frecuentes sí tienen ficha propia en Errores de Meta.
Si un código no está
Sección titulada «Si un código no está»- No trae código: es un error de la cuarta forma (
{ statusCode, message, error }). Se busca por el texto del mensaje y la ruta en los registros del servidor. - Es nuevo: alguien lo agregó al backend y todavía no llegó aquí. El chequeo del catálogo de errores del backend falla mientras un código no esté documentado, así que basta con sincronizar.
Cómo se mantiene
Sección titulada «Cómo se mantiene»La fuente es el catálogo de errores de BoostAPI: lo que significa cada código se escribe allá, junto al código, y el resto se lee del código mismo. Esta documentación guarda una copia pública de ese catálogo (sin rutas de API, historia interna ni datos de clientes) y la actualiza con npm run errores:sync. El paso a paso está en Mantener esta documentación.
Copia actual: 849 códigos en 33 familias, del catálogo del 2026-10-21 (BoostAPI 16cf19ff).