Códigos de error

Formato de respuesta

Ejemplo de respuesta Problem. Consulta la referencia del endpoint para conocer su estado HTTP, tipo de contenido y esquema de respuesta:

{
  "title": "A template named in the onboarding override is missing values only the caller can provide",
  "status": 422,
  "detail": "A template named in the onboarding override is missing values only the caller can provide",
  "code": "BRIDGE_CONVERSATION_0604",
  "extra": {
    "templateId": "f0000040-0000-4000-8000-000000000040",
    "missingVariables": [{ "key": "delivery_date", "label": "Delivery date" }]
  },
  "instance": "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/conversations",
  "traceId": "Root=1-6702b8c4-3f1a2b4c5d6e7f8091a2b3c4"
}

Campo	Significado
`code`	Cuando aparece, código estable de error incluido en esta página. Decide qué hacer según este campo, no según el título. Los errores de validación y del servidor pueden omitirlo.
`title`	Mensaje legible para personas. Puede ser más largo que el título de las tablas siguientes: nunca lo uses para identificar el error
`status`	Código de estado HTTP
`detail`	Más información sobre este caso, cuando está disponible
`extra`	Contexto estructurado para procesar el error, como los IDs o claves involucrados, cuando está disponible
`instance`	URL de la solicitud
`traceId`	Inclúyelo cuando contactes a soporte

Lee el esquema de respuesta de la operación que llamas. Cuando sea HTTPValidationError, los detalles están en un array detail; cada entrada contiene loc —dónde—, msg —qué— y type. Otras respuestas 422 documentadas usan Problem y pueden incluir code y extra. No asumas que todas las respuestas 422 tienen el mismo formato.

Interpreta los errores de validación de forma defensiva

Acepta cuerpos de error JSON con application/json o application/problem+json. Comprueba primero el estado HTTP y después revisa el cuerpo:

Si aparece code, usa la entrada correspondiente de esta página para decidir qué hacer.
Si errors es un array, lee sus entradas loc, msg y type como detalles de validación.
Si detail es un array, interprétalo como el formato HTTPValidationError. Un detail de tipo cadena es una explicación, no una lista de errores de campos.
Conserva traceId, el estado y la URL de solicitud para soporte. No exijas la presencia de code o extra ni uses mensajes legibles como identificadores.

Un campo inválido y una regla que relaciona varios campos no tienen por qué compartir el mismo estado. Las reglas del cuerpo saliente revisadas generan 400 con BRIDGE_CORE_0103 cuando consent.status es GRANTED y no se incluye capturedAt, o cuando template.media proporciona ambos o ninguno de mediaId y url. Los tipos de campo o UUID inválidos pueden producir, en cambio, detalles de validación de solicitud con 422. Interpreta juntos el estado y el cuerpo de error; no exijas un array errors para toda solicitud inválida.

Códigos heredados con sufijo

Algunos manejadores de errores heredados añaden un nombre simbólico a code, por ejemplo, BRIDGE_PRELOAD_FILE_0002 | PRELOAD_FILE_IS_PENDING. Conserva el valor recibido completo para registros y soporte. Para consultar el catálogo, acepta un código simple conocido o su forma heredada reconocida explícitamente; no compares title o detail, no inventes un código desconocido ni reescribas el cuerpo de la respuesta. Esta revisión del código fuente no ha confirmado de forma independiente qué versión del manejador está desplegada.

Compatibilidad de validación: algunas respuestas OpenAPI publicadas declaran HTTPValidationError.detail[] y application/json, mientras que el manejador compartido de errores de la API revisado para esta documentación devuelve detalles de validación en Problem.errors[] con application/problem+json. Esta actualización editorial conserva las definiciones de respuesta publicadas. Maneja ambos formatos; sigue pendiente la confirmación contra la API desplegada antes de admitir solo uno en un cliente generado estricto.

Decide si debes reintentar

Resultado	Acción
`400` o `422`	Corrige la solicitud según el código y los errores de campos. Repetir la misma entrada no corrige la validación.
`401` o `403`	Revisa las credenciales, el espacio de trabajo y los permisos del tipo de integración correcto. Guarda las claves REST en el servidor.
`404`	Confirma el identificador y el espacio de trabajo. Una consulta sin contacto coincidente es distinta de una entrada mal formada.
`409`	Lee el código de la operación: una conversación existente, un agente no disponible o una sesión pendiente requieren soluciones distintas. No habilites `forceSend` automáticamente.
`429`	Sigue la guía de encabezados y espera por límite de solicitudes.
Tiempo de espera agotado, respuesta desconectada o `5xx` después de una escritura	Trata el resultado como incierto. Revisa el recurso afectado antes de reenviar: un error no demuestra que no se haya guardado ningún cambio.

Esta guía general de reintentos no agrega idempotencia a un endpoint. Para reutilización, recuperación y escrituras parciales, consulta Conversaciones salientes y transferencias de agentes. Custom Connections tiene su propia referencia de errores y no usa una clave de la API REST.

Errores al responder a un mensaje

Para POST .../messages, las comprobaciones revisadas del mensaje al que respondes definen estas formas heredadas adicionales:

BRIDGE_MESSAGE_0001 | MESSAGE_NOT_FOUND (404): no se encontró el Message indicado en replyToMessageId.
BRIDGE_MESSAGE_0002 | MESSAGE_IS_NOT_ON_CONVERSATION (403): el mensaje al que respondes pertenece a otra Conversation. Usa uno de la Conversation en la que vas a enviar el mensaje.

Conserva code completo, incluido su sufijo simbólico. Estas comprobaciones se refieren al mensaje al que respondes, no al mediaId del archivo adjunto.

Errores de carga de archivos

El flujo de carga revisado define estos códigos heredados. El sufijo forma parte del code recibido, no es un campo de la solicitud. Consulta el contrato de respuesta de la operación y conserva la interpretación compatible anterior. La operación determina qué errores de archivo corresponden: POST .../files comprueba los metadatos y puede devolver los códigos 0003 o 0004 de abajo. POST .../messages puede devolver 0001 o 0002 cuando el mediaId de un adjunto no existe o sigue pendiente. Los archivos de las plantillas salientes tienen su propio manejo de errores; no sustituyas BRIDGE_AI_LEADSCOUT_0016 por estos códigos.

`code` heredado	Estado	Acción
`BRIDGE_PRELOAD_FILE_0001 \| PRELOAD_FILE_NOT_FOUND`	404	Comprueba el `mediaId` devuelto y la carga a la que hace referencia.
`BRIDGE_PRELOAD_FILE_0002 \| PRELOAD_FILE_IS_PENDING`	400	El archivo sigue pendiente. Confirma que el PUT terminó y permite que se procese la carga; no deduzcas que una solicitud de Message fallida no guardó ningún cambio.
`BRIDGE_PRELOAD_FILE_0003 \| PRELOAD_FILE_INVALID_MIME_TYPE`	400	Corrige la combinación del tipo MIME y el `fileType` lógico.
`BRIDGE_PRELOAD_FILE_0004 \| PRELOAD_FILE_INVALID_NAME`	400	Proporciona un nombre con una extensión admitida para ese `fileType` lógico.

Códigos de error de agentes

Errores de las operaciones de agentes.

Código	Referencia en inglés	Mensaje
`BRIDGE_AI_AGENT_OUTBOUND_0001`	Agent Not Found	No se encontró el agente en el espacio de trabajo
`BRIDGE_AI_AGENT_OUTBOUND_0002`	Agent Not Available	El agente no está disponible para conversaciones salientes
`BRIDGE_AI_AGENT_OUTBOUND_0003`	Agent Type Not Supported	El tipo de agente no admite conversaciones salientes
`BRIDGE_AI_AGENT_OUTBOUND_0004`	No Channels For Agent	El agente no tiene una línea activa de mensajería vinculada
`BRIDGE_AI_AGENT_OUTBOUND_0005`	Agent Not Assigned To Channel	El agente no está asignado al canal solicitado
`BRIDGE_AI_AGENT_OUTBOUND_0006`	Conversation Controlled By Other Agent	Otro agente controla la conversación activa
`BRIDGE_AI_AGENT_OUTBOUND_0007`	Invalid Cursor	El cursor de paginación está mal formado o pertenece a otro espacio de trabajo

POST .../agents/{agentId}/outbound devuelve 0001 y 0004 como 404, 0002 y 0006 como 409, y 0003 y 0005 como 422.

0002: el agente está en borrador o no tiene una línea. extra.reason indica la causa; esa misma causa aparece en unavailableReason en GET .../agents.
0006: la conversación del contacto en la línea seleccionada por la solicitud está controlada por otro agente o por un usuario de Bridge. No se envió nada. Libérala con POST .../conversations/{conversationId}/release, usando extra.conversationId, y vuelve a intentar. extra también incluye channelId y, solo si la controla un agente, controllingAgentId, que identifica a ese agente. Cuando la controla un usuario de Bridge, la clave no aparece; no se devuelve null.

GET .../agents devuelve 0007 como 400 cuando el cursor está mal formado o se emitió para otro espacio de trabajo. Empieza otra vez sin cursor. Conserva el mismo filtro type durante la paginación: un cursor emitido con un filtro type se rechaza si la solicitud usa otro type.

Otros códigos de `POST .../agents/{agentId}/outbound`

Código	Estado	Significado
`BRIDGE_CORE_0103`	400	La solicitud es inválida: `consent.status` es `GRANTED` sin `capturedAt`, `template` no incluye `id` ni `name`, o `template.media` no incluye exactamente uno de `mediaId` o `url`
`BRIDGE_CORE_0301`	403	El espacio de trabajo de la ruta no coincide con el de la clave de API
`BRIDGE_AI_LEADSCOUT_0001`	404	El contacto no existe en el espacio de trabajo
`BRIDGE_AI_LEADSCOUT_0002`	404	El usuario de Bridge de `handoffOverride` no existe en el espacio de trabajo
`BRIDGE_AI_LEADSCOUT_0003`	409	Se eliminó al usuario de Bridge de `handoffOverride`
`BRIDGE_AI_LEADSCOUT_0004`	404	Ninguna plantilla del espacio de trabajo coincide con `template.id`, o con `template.name` cuando no se envía un ID
`BRIDGE_AI_LEADSCOUT_0005`	409	La plantilla no está aprobada
`BRIDGE_AI_LEADSCOUT_0006`	400	No coinciden los parámetros ordenados de la plantilla
`BRIDGE_AI_LEADSCOUT_0007`	409	Ya existe una conversación activa: otra solicitud obtuvo primero la conversación liberada. Reintenta
`BRIDGE_AI_LEADSCOUT_0008`	409	Ninguna línea del agente está libre o es recuperable para este contacto; consulta `forceSend`
`BRIDGE_AI_LEADSCOUT_0009`	404	No hay una línea configurada para el `brandId` solicitado
`BRIDGE_AI_LEADSCOUT_0016`	400	Error de validación de conversación saliente
`BRIDGE_AI_LEADSCOUT_0017`	409	La sesión más reciente no está finalizada
`BRIDGE_AI_LEADSCOUT_0018`	409	No se pudo finalizar la sesión vencida antes de iniciar otra
`BRIDGE_AI_LEADSCOUT_0019`	422	Faltan una o más variables obligatorias de la plantilla
`BRIDGE_AI_LEADSCOUT_0020`	422	Hay fuentes de parámetros de plantilla superpuestas para la misma posición
`BRIDGE_AI_LEADSCOUT_0021`	422	Clave de parámetro de plantilla desconocida

En POST .../agents/{agentId}/outbound, los errores 5xx no incluyen code ni extra.

Códigos de error de LeadScout

Códigos adicionales documentados para iniciar una conversación saliente de LeadScout mediante POST .../leadscout/outbound:

Código	Estado	Referencia en inglés	Significado
`BRIDGE_AI_LEADSCOUT_0010`	404	Channel Not In Workspace	El canal de proveedor no pertenece al espacio de trabajo
`BRIDGE_AI_LEADSCOUT_0011`	404	No Provider Channels	El espacio de trabajo no tiene canales de proveedor
`BRIDGE_AI_LEADSCOUT_0012`	404	No Agent For Channel	No hay un agente de prospección para el canal
`BRIDGE_AI_LEADSCOUT_0013`	409	Multiple Agents For Brand	Hay varios agentes de prospección para la marca
`BRIDGE_AI_LEADSCOUT_0014`	409	Multiple Agents For Channel	Hay varios agentes de prospección para el canal
`BRIDGE_AI_LEADSCOUT_0015`	500	Conversation Operation Failed	Falló la operación de conversación

Códigos de error de marcas

Errores de comprobación de marcas al crear una conversación.

Código	Referencia en inglés	Mensaje
`BRIDGE_BRAND_0101`	Brand Required	El espacio de trabajo tiene marcas habilitadas; cada participante externo debe corresponder a una marca o línea

Se devuelve como 400. Envía brandId o providerChannelId para cada participante externo; extra.resources enumera los participantes que no tenían ninguno de los dos.

Códigos de error de conversaciones

Errores de las operaciones de conversaciones.

Código	Referencia en inglés	Mensaje
`BRIDGE_CONVERSATION_0001`	Conversation Not Found	No se encontró la conversación solicitada
`BRIDGE_CONVERSATION_0002`	Conversation Not In Workspace	La conversación no pertenece al espacio de trabajo especificado
`BRIDGE_CONVERSATION_0003`	Conversation With Same Participants Already Exists	Ya existe una conversación activa con los mismos participantes
`BRIDGE_CONVERSATION_0004`	Conversation Not Active	La conversación está inactiva y no se pueden hacer operaciones sobre ella
`BRIDGE_CONVERSATION_0005`	Conversation Operation Failed	Ocurrió un error al operar sobre la conversación
`BRIDGE_CONVERSATION_0006`	Conversation With Inconsistent State	La conversación tiene un estado inconsistente; contacta a soporte para resolverlo
`BRIDGE_CONVERSATION_0007`	Conversation Is Released	La conversación está liberada: `409` en `POST .../messages`
`BRIDGE_CONVERSATION_0101`	Internal User Already In Conversation	El usuario interno ya participa en la conversación
`BRIDGE_CONVERSATION_0102`	Internal User Not In Conversation	El usuario interno no participa en la conversación
`BRIDGE_CONVERSATION_0103`	External User Already In Conversation	El usuario externo ya participa en la conversación
`BRIDGE_CONVERSATION_0104`	External User Not In Conversation	El usuario externo no participa en la conversación
`BRIDGE_CONVERSATION_0105`	External User Already Use This Channel	El usuario externo ya usa este canal de mensajería en otra conversación
`BRIDGE_CONVERSATION_0201`	External Participants Required	Se requiere al menos un participante externo para operar en una conversación
`BRIDGE_CONVERSATION_0202`	Internal Participants Required	Se requiere al menos un participante interno para operar en una conversación
`BRIDGE_CONVERSATION_0203`	User Is Not Admin	El usuario no es administrador de esta conversación
`BRIDGE_CONVERSATION_0204`	Last Admin Removal Forbidden	La conversación debe tener al menos un administrador
`BRIDGE_CONVERSATION_0205`	Min Internal Users Required	La conversación debe tener una cantidad mínima de participantes internos
`BRIDGE_CONVERSATION_0206`	Max Internal Participants Exceeded	Se superó el máximo de participantes internos de la conversación
`BRIDGE_CONVERSATION_0207`	Min External Participants Required	La conversación debe tener una cantidad mínima de participantes externos
`BRIDGE_CONVERSATION_0208`	Max External Participants Exceeded	Se superó el máximo de participantes externos de la conversación
`BRIDGE_CONVERSATION_0210`	Min Participants Required	La conversación debe tener una cantidad mínima de participantes
`BRIDGE_CONVERSATION_0211`	Max Participants Exceeded	La conversación debe respetar una cantidad máxima de participantes
`BRIDGE_CONVERSATION_0212`	Max Initial Messages Exceeded	Se superó el máximo de mensajes iniciales
`BRIDGE_CONVERSATION_0213`	Messages Not In Conversation	Los mensajes deben pertenecer a la misma conversación
`BRIDGE_CONVERSATION_0601`	Onboarding Template Not Found	No existe una plantilla indicada en el reemplazo de plantillas de inicio
`BRIDGE_CONVERSATION_0602`	Onboarding Template Not In Workspace	Una plantilla indicada en el reemplazo de inicio pertenece a otro espacio de trabajo
`BRIDGE_CONVERSATION_0603`	Onboarding Template Not Approved	Una plantilla indicada en el reemplazo de inicio no está aprobada para la línea usada para contactar a un participante
`BRIDGE_CONVERSATION_0604`	Onboarding Template Missing Parameters	Faltan en una plantilla de inicio valores que solo puede proporcionar quien hace la solicitud
`BRIDGE_CONVERSATION_0605`	Onboarding Template Unknown Parameters	El reemplazo de inicio nombra parámetros que la plantilla no declara
`BRIDGE_CONVERSATION_0606`	Onboarding Template Parameters Not Supported	Se enviaron parámetros para una plantilla de inicio que no es una plantilla de proveedor de WhatsApp
`BRIDGE_CONVERSATION_0607`	Onboarding Template Invalid Parameter Values	Los valores de parámetros de una plantilla de inicio infringen una regla de WhatsApp y se rechazarían al enviarse
`BRIDGE_CONVERSATION_0608`	Onboarding Configured Template Requires Caller Input	Una plantilla de la secuencia de inicio del espacio de trabajo necesita valores que solo puede proporcionar quien hace la solicitud; un administrador debe cambiar la secuencia

Al crear una conversación, BRIDGE_CONVERSATION_0105 devuelve 409 con extra.reason igual a PARTICIPANTS_MISMATCH: una conversación liberada ocupa la línea del contacto con otros contactos o líneas. Solicita los mismos contactos y líneas o usa otra línea. BRIDGE_CONVERSATION_0601 devuelve 404, 0602 y 0603 devuelven 400, y 0604 a 0608 devuelven 422. Consulta Parámetros de plantillas de inicio para saber qué incluye cada uno en extra y cómo corregirlo.

Códigos de error de usuarios externos

Errores de las operaciones de usuarios externos o contactos.

Código	Referencia en inglés	Mensaje
`BRIDGE_EXTERNAL_0001`	External User Not Found	No se encontró el usuario externo solicitado
`BRIDGE_EXTERNAL_0002`	External User Already Exists	Ya existe un usuario externo con los mismos datos de identificación
`BRIDGE_EXTERNAL_0004`	External User Not In Workspace	Uno o más usuarios externos no pertenecen al espacio de trabajo especificado
`BRIDGE_EXTERNAL_0005`	External User Without Configured Field	El usuario externo no tiene un campo configurado; revisa la configuración del espacio de trabajo o de información externa
`BRIDGE_EXTERNAL_0007`	Cellphone Owned By Another Contact	El teléfono ya es una identidad activa de otro usuario externo
`BRIDGE_EXTERNAL_0013`	Email Owned By Another Contact	El correo ya es una identidad activa de otro usuario externo
`BRIDGE_EXTERNAL_0101`	External User Operation Failed	Ocurrió un error al operar sobre el usuario externo

Códigos de error de usuarios internos

Errores de las operaciones de usuarios internos.

Código	Referencia en inglés	Mensaje
`BRIDGE_INTERNAL_0001`	Internal User Not Found	No se encontró el usuario interno
`BRIDGE_INTERNAL_0002`	Internal Users Not In Workspace	Los usuarios internos proporcionados no pertenecen al espacio de trabajo especificado
`BRIDGE_INTERNAL_0003`	Inactive Internal User	Uno o más usuarios internos están inactivos en el espacio de trabajo; revisa su estado en la configuración
`BRIDGE_INTERNAL_0004`	Internal User Without Configured Field	El usuario interno no tiene un campo configurado; revisa la configuración del espacio de trabajo o de información interna
`BRIDGE_INTERNAL_0101`	Internal User Does Not Support Operation	El usuario interno no admite esta operación

Códigos de error de canales de proveedor

Errores de las operaciones de canales de proveedor.

Código	Referencia en inglés	Mensaje
`BRIDGE_PROVIDER_CHANNEL_0001`	Provider Channel Not Found	No se encontró el canal de proveedor; verifica que el espacio de trabajo tenga canales configurados

Al crear una conversación, este código se devuelve como 409 cuando no hay una línea de WhatsApp libre para un contacto ni una conversación liberada que recuperar, o cuando el providerChannelId indicado no está disponible para ese contacto.

Códigos de error de límites de solicitudes

Errores devueltos cuando un espacio de trabajo supera su presupuesto de solicitudes. Consulta el presupuesto, los encabezados y un cliente que regula su ritmo en Límites de solicitudes.

Código	Referencia en inglés	Mensaje
`BRIDGE_RATE_LIMIT_0001`	Too Many Requests	El espacio de trabajo agotó el presupuesto de solicitudes de la ventana actual

Este es el único código que debe reintentarse automáticamente, y solo después de la espera indicada por Retry-After. Los fallos de autenticación no son errores de límite de solicitudes y reintentarlos de forma programada no los resolverá.

Códigos de error de solicitudes

Errores devueltos antes de ejecutar una operación cuando la propia solicitud no se puede procesar. Consulta en el Registro de cambios los parámetros que un endpoint dejará de aceptar.

Código	Referencia en inglés	Mensaje
`BRIDGE_CORE_0101`	Invalid Field Format	El formato del campo es inválido; proporciona un valor válido
`BRIDGE_CORE_0102`	Missing Required Field	Faltan campos obligatorios; revisa la operación
`BRIDGE_CORE_0103`	Bad Request	La solicitud es inválida; revisa el cuerpo y los parámetros
`BRIDGE_CORE_0104`	Invalid Cursor	El cursor es inválido; usa uno obtenido de una respuesta anterior

No reintentes ninguno de estos casos sin hacer cambios. detail describe el problema y, cuando es posible, indica el campo o parámetro incorrecto; la misma solicitud fallará igual hasta que la modifiques.

Códigos de error de plantillas

Errores de las operaciones de plantillas.

Código	Referencia en inglés	Mensaje
`BRIDGE_TEMPLATE_0001`	Provider Template Not Found	No se encontró una plantilla de proveedor para el espacio de trabajo y nombre indicados

GET .../templates/{templateId} lo devuelve como 404 cuando el ID o nombre no coincide con una plantilla de WhatsApp de tu espacio de trabajo.

Códigos de error de espacios de trabajo

Errores de las operaciones de espacios de trabajo.

Código	Referencia en inglés	Mensaje
`BRIDGE_WORKSPACE_0001`	Workspace Not Found	No se encontró el espacio de trabajo solicitado
`BRIDGE_WORKSPACE_0002`	Workspace Not In Organization	El espacio de trabajo no pertenece a la organización especificada
`BRIDGE_WORKSPACE_0003`	Workspace Without Available Provider Channels	El espacio de trabajo no tiene canales de proveedor disponibles
`BRIDGE_WORKSPACE_0004`	Workspace Without Configured Field	El espacio de trabajo no tiene un campo configurado: `409` en `POST .../conversations/{conversationId}/release`

Empieza aquí

Crea tu integración

Referencia

Formato de respuesta

Interpreta los errores de validación de forma defensiva

Códigos heredados con sufijo

Decide si debes reintentar

Errores al responder a un mensaje

Errores de carga de archivos

Códigos de error de agentes

Otros códigos de `POST .../agents/{agentId}/outbound`

Códigos de error de LeadScout

Códigos de error de marcas

Códigos de error de conversaciones

Códigos de error de usuarios externos

Códigos de error de usuarios internos

Códigos de error de canales de proveedor

Códigos de error de límites de solicitudes

Códigos de error de solicitudes

Códigos de error de plantillas

Códigos de error de espacios de trabajo

Formato de respuesta

Interpreta los errores de validación de forma defensiva

Códigos heredados con sufijo

Decide si debes reintentar

Errores al responder a un mensaje

Errores de carga de archivos

Códigos de error de agentes

Otros códigos de POST .../agents/{agentId}/outbound

Códigos de error de LeadScout

Códigos de error de marcas

Códigos de error de conversaciones

Códigos de error de usuarios externos

Códigos de error de usuarios internos

Códigos de error de canales de proveedor

Códigos de error de límites de solicitudes

Códigos de error de solicitudes

Códigos de error de plantillas

Códigos de error de espacios de trabajo

Otros códigos de `POST .../agents/{agentId}/outbound`