Versión de la API: 4.x más reciente 3.x

Estás viendo la documentación de la API de BigBlueButton 3.x. La versión actual es BigBlueButton 4.x. ¿Planeas una actualización? La guía de migración enumera todos los cambios que necesitan tus llamadas a la API.

Capítulo 23

Referencia de errores de la API

Las solicitudes fallidas a la API de BigBlueButton devuelven una respuesta de error XML estandarizada. Este capítulo ofrece una referencia de los códigos y mensajes de error que puede devolver la API, basada en el análisis del código fuente de BigBlueButton 3.0.

Formato de respuesta de error

Cuando falla una llamada API, BigBlueButton devuelve una respuesta XML con tres elementos clave: un returncode, un messageKey legible por máquina y un message legible por humanos. Toda respuesta de error sigue esta estructura:

<response>
  <returncode>FAILED</returncode>
  <messageKey>errorKeyHere</messageKey>
  <message>A human-readable description of the error.</message>
</response>

Excepciones: nonUniqueVoiceBridge y clientSettingsOverrideValidationError se devuelven como una lista errors con elementos key y message en lugar de messageKey y message. Los endpoints basados en sesiones getJoinUrl, learningDashboard y stuns devuelven los errores en JSON con un message, pero sin un messageKey.

El returncode siempre es FAILED para los errores. La única excepción es duplicateWarning, que devuelve SUCCESS pero incluye una clave de mensaje de advertencia. Tu integración debe comprobar siempre el campo messageKey, no solo el código de retorno.

Errores de autenticación y autorización

Estos errores ocurren cuando una solicitud no puede autenticarse o cuando quien llama no tiene los permisos requeridos:

messageKey Mensaje Endpoints que lo activan
checksumError El checksum no coincide. Todos los endpoints que requieren una suma de comprobación
invalidPassword La contraseña proporcionada no es válida. create, join, end
guestDeniedAccess Acceso denegado según la política de invitados. join
apiNotEnabled El servicio API no está habilitado en este servidor. Todos los endpoints

Errores de gestión de reuniones

Estos errores están relacionados con la creación, unión y gestión de reuniones:

messageKey Mensaje Endpoints que lo activan
notFound No existe una reunión con este ID. getMeetingInfo, end
invalidMeetingIdentifier No existe una reunión con este ID. join
meetingForciblyEnded No se puede unirse a una reunión que ha sido finalizada forzosamente. join
idNotUnique Ya existe una reunión con este ID. create
nonUniqueVoiceBridge El puente de voz seleccionado ya está en uso. create
duplicateWarning Esta conferencia ya existe y puede estar en ejecución. returncode es SUCCESS create
mismatchCreateTimeParam El parámetro createTime no coincide con la reunión actual. join
maxParticipantsReached Se ha alcanzado el número máximo de participantes. join
parentMeetingIDMissing No se especificó parentMeetingID para la sala de grupos. create (breakout)
parentMeetingDoesNotExist No se encontró ninguna reunión principal para la sala de grupos. create (breakout)
meetingNotFound No se encontró la reunión. sendChatMessage
Params required No se envió un rol válido o la contraseña no coincide ni con la del moderador ni con la del asistente. join
clientSettingsOverrideValidationError La configuración que sobrescribe los ajustes del cliente contiene claves desconocidas o mal formadas (solo se comprueba cuando clientSettingsOverrideStrictValidation está habilitado). create

Errores de validación de parámetros

Estos errores se devuelven cuando faltan parámetros obligatorios o cuando los datos de la solicitud no superan la validación:

messageKey Mensaje Endpoints que lo activan
missingParamMeetingID Debe proporcionarse el ID de reunión. create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage
missingParamFullName Debe proporcionarse fullName. join
missingParamRecordID Debe proporcionarse el ID de grabación. updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks
missingParamPublish Debe proporcionarse el valor publish (true/false). publishRecordings
validationError Error general de validación (varios mensajes). Múltiples endpoints
unsupportedContentType Falta el Content-Type de la solicitud POST o no es compatible. create, join, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage
emptyError El campo no debe estar vacío. Validación general
nullError Falta un valor obligatorio. create, sendChatMessage
sizeError La longitud de un parámetro está fuera del intervalo permitido. create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage

Errores de grabación

Estos errores son específicos de la gestión de grabaciones y de las operaciones de pistas de texto:

messageKey Mensaje Endpoints que lo activan
notFound No se encontraron grabaciones. updateRecordings, publishRecordings, deleteRecordings
noRecordings No se encontró ninguna grabación para el ID de grabación especificado. getRecordingTextTracks, putRecordingTextTrack
empty_uploaded_text_track El archivo de pista de texto subido está vacío. putRecordingTextTrack
paramError Falta el parámetro {paramName} (dinámico). putRecordingTextTrack
invalidKind Parámetro kind inválido — se esperaba: subtitles o captions. putRecordingTextTrack
invalidLang Parámetro language no válido. putRecordingTextTrack

Errores de sesión y usuario

Estos errores ocurren durante la validación de la sesión y del usuario:

messageKey Mensaje Endpoints que lo activan
userNotFound No se encontró ninguna sesión activa para el ID de usuario especificado. join (con existingUserID)

Solución de problemas

Cuando encuentres un error de API, sigue estos pasos para diagnosticar y resolver el problema:

Comprueba el messageKey — usa las tablas de códigos de error anteriores para identificar la causa exacta del fallo y qué endpoint lo provocó.

Verifica tu suma de comprobación: el error más común es checksumError. Comprueba que estás utilizando el secreto compartido correcto y el algoritmo hash adecuado, y que la cadena de consulta coincide exactamente.

Revisa los parámetros obligatorios: los errores de parámetros ausentes (missingParamMeetingID, missingParamFullName, etc.) indican que no se ha incluido un campo obligatorio en la solicitud.

Confirma el estado de la reunión: errores como notFound o invalidMeetingIdentifier significan que la reunión no existe o ya ha finalizado. Utiliza getMeetingInfo para verificar el estado actual antes de volver a intentarlo.

Revisa los registros del servidor — si el mensaje de error no es lo suficientemente específico, consulta los registros del servidor BigBlueButton en /var/log/bigbluebutton/ para obtener información más detallada.

Algunos mensajes de error son dinámicos e incluyen el nombre o el valor del parámetro problemático. Registra siempre la respuesta XML completa de la API para facilitar la depuración.

Al gestionar la clave de mensaje duplicateWarning, ten en cuenta que el returncode es SUCCESS, no FAILED. Este es un caso especial en el que BigBlueButton señala que ya existe una reunión con el mismo ID, pero devuelve los datos de la reunión existente en lugar de generar un error.

Preguntas frecuentes

Los códigos de error enumerados en esta referencia se extraen directamente del código fuente de BigBlueButton 3.0. La documentación oficial de BBB no incluye una referencia completa de errores. Las definiciones están repartidas en varios archivos de código fuente, incluidos ApiErrors.java, ApiController.groovy y RecordingController.groovy.

Sí. Aunque los valores de messageKey tienden a mantenerse estables entre versiones, el texto del mensaje legible por humanos puede cambiar. Usa siempre messageKey para el manejo programático de errores, no la cadena del mensaje.

Los tres indican que la reunión solicitada no está disponible, pero los devuelven distintos endpoints. getMeetingInfo, end utiliza notFound, join utiliza invalidMeetingIdentifier y sendChatMessage utiliza meetingNotFound (también cuando la reunión existe, pero nadie se ha unido a ella). isMeetingRunning nunca falla si la reunión es desconocida; devuelve <running>false</running>.

duplicateWarning es un caso especial: el returncode es SUCCESS, pero el messageKey indica que ya existe una reunión con el mismo ID. Tu aplicación debe comprobar si los parámetros de la reunión existente coinciden con lo que pretendías. Si coinciden, puedes continuar con seguridad. Si no, elige un ID de reunión diferente.

Las causas más comunes son: usar el secreto compartido incorrecto, aplicar el algoritmo hash equivocado, codificar la cadena de consulta de forma inconsistente en URL o incluir el propio parámetro checksum en la entrada del hash. Asegúrate de que la cadena que calculas se construye así: apiMethodName + queryString + sharedSecret, donde queryString no incluye el parámetro checksum.

Este error se devuelve cuando una solicitud con cuerpo carece de la cabecera Content-Type o utiliza un tipo de contenido que BigBlueButton no admite para ese endpoint. Utiliza application/x-www-form-urlencoded para los parámetros de formulario; create también acepta un cuerpo XML, y insertDocument solo acepta application/xml o text/xml.

BigBlueButton puede devolver códigos de error adicionales procedentes de plugins o módulos personalizados que no forman parte de la API principal. Los códigos enumerados aquí cubren la API principal de BigBlueButton 3.0. Si encuentras un messageKey no reconocido, consulta los registros del servidor y los plugins instalados para obtener más información.