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.
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
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.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.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.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.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.messageKey no reconocido, consulta los registros del servidor y los plugins instalados para obtener más información.