Capítulo 23

Referencia de errores de la API

Cada solicitud fallida a la API de BigBlueButton devuelve una respuesta de error XML estandarizada. Este capítulo proporciona una referencia completa de todos los códigos y mensajes de error que la API puede devolver, 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>

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
invalidPassword La contraseña proporcionada no es válida. join, end
guestDeniedAccess Acceso denegado según la política de invitados. join
missingToken Falta el token de sesión. getJoinUrl, learningDashboard
missingSession El token de sesión es inválido. getJoinUrl, learningDashboard
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
invalidMeetingId El ID de reunión especificado no existe. getMeetingInfo, isMeetingRunning, end, join
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, getJoinUrl, learningDashboard

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
MissingParam Falta el parámetro obligatorio {param} (dinámico). create, join, end, getMeetingInfo, y otros
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, end, getMeetingInfo, insertDocument, sendChatMessage
emptyError El campo no debe estar vacío. Validación general
fileNameError No se pudo decodificar el nombre del archivo. insertDocument

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. 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)
configNotFound No se encontró configuración para este token. Validación interna
noConfigFound No se encontró configuración para esta solicitud. Validación interna

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ó.

— el error más común es checsumError. Comprueba dos veces que estás usando el secreto compartido correcto, el algoritmo hash adecuado y que la cadena de consulta coincide exactamente.

Inspecciona los parámetros requeridos: los errores de parámetro faltante (MissingParam, missingParamMeetingID, etc.) indican que un campo obligatorio no se incluyó en la solicitud.

Confirma el estado de la reunión: errores como invalidMeetingId o meetingForciblyEnded significan que la reunión no existe o ya ha terminado. Usa 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 entre varios archivos 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.

Ambos indican que la reunión solicitada no existe, pero son devueltos por endpoints diferentes. invalidMeetingId se usa en getMeetingInfo, isMeetingRunning, end y join. meetingNotFound se usa en sendChatMessage, getJoinUrl y learningDashboard.

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 a una solicitud POST le falta la cabecera Content-Type o usa un tipo de contenido que BigBlueButton no admite. Asegúrate de que tus solicitudes POST incluyan la cabecera Content-Type: application/x-www-form-urlencoded.

BigBlueButton puede devolver códigos de error adicionales 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 cualquier plugin instalado para obtener más información.