Chapitre 23

Référence des erreurs de l’API

Chaque requête API BigBlueButton échouée renvoie une réponse d’erreur XML standardisée. Ce chapitre fournit une référence complète de tous les codes et messages d’erreur que l’API peut renvoyer, sur la base de l’analyse du code source de BigBlueButton 3.0.

Format de réponse d'erreur

Lorsqu’un appel API échoue, BigBlueButton renvoie une réponse XML avec trois éléments clés : un returncode, un messageKey lisible par machine et un message lisible par l’humain. Chaque réponse d’erreur suit cette structure : 

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

Le returncode est toujours FAILED pour les erreurs. La seule exception est duplicateWarning, qui renvoie SUCCESS mais inclut une clé de message d'avertissement. Votre intégration doit toujours vérifier le champ messageKey, et pas seulement le code de retour.

Erreurs d'authentification et d'autorisation

Ces erreurs se produisent lorsqu'une requête ne peut pas être authentifiée ou lorsque l'appelant ne dispose pas des autorisations requises :

messageKey Message Endpoints déclencheurs
checksumError Le checksum ne correspond pas. Tous les points de terminaison
invalidPassword Le mot de passe fourni est invalide. join, end
guestDeniedAccess Accès refusé selon la politique invité. join
missingToken Le token de session est manquant. getJoinUrl, learningDashboard
missingSession Le token de session est invalide. getJoinUrl, learningDashboard
apiNotEnabled Le service API n'est pas activé sur ce serveur. Tous les points de terminaison

Erreurs de gestion des réunions

Ces erreurs concernent la création, la participation et la gestion des réunions :

messageKey Message Endpoints déclencheurs
invalidMeetingId L’ID de réunion spécifié n’existe pas. getMeetingInfo, isMeetingRunning, end, join
invalidMeetingIdentifier Aucune réunion avec cet identifiant n'existe. join
meetingForciblyEnded Impossible de rejoindre une réunion qui a été forcée à se terminer. join
idNotUnique Une réunion avec cet identifiant existe déjà. create
nonUniqueVoiceBridge Le pont vocal sélectionné est déjà utilisé. create
duplicateWarning Cette conférence existe déjà et est peut-être en cours. returncode est SUCCESS create
mismatchCreateTimeParam Le paramètre createTime ne correspond pas à la réunion actuelle. join
maxParticipantsReached Le nombre maximal de participants a été atteint. join
parentMeetingIDMissing Aucun parentMeetingID spécifié pour la salle de répartition. create (breakout)
parentMeetingDoesNotExist Aucune réunion parente trouvée pour la salle de répartition. create (breakout)
meetingNotFound La réunion est introuvable. sendChatMessage, getJoinUrl, learningDashboard

Erreurs de validation des paramètres

Ces erreurs sont renvoyées lorsque des paramètres obligatoires sont manquants ou lorsque les données de la requête échouent à la validation :

messageKey Message Endpoints déclencheurs
MissingParam Le paramètre obligatoire {param} est manquant (dynamique). create, join, end, getMeetingInfo, et autres
missingParamMeetingID L’ID de réunion doit être fourni. create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage
missingParamFullName Le fullName doit être fourni. join
missingParamRecordID L’ID d’enregistrement doit être fourni. updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks
missingParamPublish La valeur publish (true/false) doit être fournie. publishRecordings
validationError Erreur générale de validation (messages divers). Plusieurs points de terminaison
unsupportedContentType Le Content-Type de la requête POST est manquant ou non pris en charge. create, join, end, getMeetingInfo, insertDocument, sendChatMessage
emptyError Le champ ne doit pas être vide. Validation générale
fileNameError Le nom du fichier n'a pas pu être décodé. insertDocument

Erreurs d'enregistrement

Ces erreurs sont spécifiques à la gestion des enregistrements et aux opérations sur les pistes de texte :

messageKey Message Endpoints déclencheurs
notFound Aucun enregistrement trouvé. updateRecordings, publishRecordings, deleteRecordings
noRecordings Aucun enregistrement trouvé pour l’ID d’enregistrement spécifié. putRecordingTextTrack
empty_uploaded_text_track Le fichier de piste texte téléversé est vide. putRecordingTextTrack
paramError Le paramètre {paramName} est manquant (dynamique). putRecordingTextTrack
invalidKind Paramètre kind invalide — attendu : subtitles ou captions. putRecordingTextTrack
invalidLang Paramètre language invalide. putRecordingTextTrack

Erreurs de session et d'utilisateur

Ces erreurs surviennent lors de la validation de la session et de l'utilisateur :

messageKey Message Endpoints déclencheurs
userNotFound Aucune session active trouvée pour l’ID utilisateur spécifié. join (avec existingUserID)
configNotFound Aucune configuration trouvée pour ce jeton. Validation interne
noConfigFound Aucune configuration trouvée pour cette requête. Validation interne

Dépannage

Lorsque vous rencontrez une erreur d’API, suivez ces étapes pour diagnostiquer et résoudre le problème :

Vérifiez le messageKey — utilisez les tableaux de codes d’erreur ci-dessus pour identifier la cause exacte de l’échec et le point de terminaison qui l’a déclenché.

— l’erreur la plus courante est checsumError. Vérifiez de nouveau que vous utilisez le bon secret partagé, le bon algorithme de hachage et que la chaîne de requête correspond exactement.

Vérifiez les paramètres requis — les erreurs de paramètre manquant (MissingParam, missingParamMeetingID, etc.) indiquent qu’un champ requis n’a pas été inclus dans la requête.

Confirmez l’état de la réunion — des erreurs comme invalidMeetingId ou meetingForciblyEnded signifient que la réunion n’existe pas ou qu’elle est déjà terminée. Utilisez getMeetingInfo pour vérifier l’état actuel avant de réessayer.

Consultez les journaux du serveur — si le message d’erreur n’est pas assez précis, consultez les journaux du serveur BigBlueButton dans /var/log/bigbluebutton/ pour obtenir des informations plus détaillées.

Certains messages d’erreur sont dynamiques et incluent le nom ou la valeur du paramètre problématique. Enregistrez toujours la réponse XML complète de l’API pour faciliter le débogage.

Lors du traitement de la clé de message duplicateWarning, notez que le returncode est SUCCESS et non FAILED. Il s’agit d’un cas particulier où BigBlueButton signale qu’une réunion avec le même ID existe déjà mais renvoie les données de la réunion existante au lieu de lever une erreur.

Foire aux questions

Les codes d’erreur listés dans cette référence sont extraits directement du code source de BigBlueButton 3.0. La documentation officielle de BBB n’inclut pas de référence d’erreurs complète. Les définitions sont réparties dans plusieurs fichiers source, notamment ApiErrors.java, ApiController.groovy et RecordingController.groovy.

Oui. Bien que les valeurs messageKey aient tendance à rester stables entre les versions, le texte du message lisible par l’humain peut changer. Utilisez toujours messageKey pour le traitement programmatique des erreurs, et non la chaîne du message.

Les deux indiquent que la réunion demandée n’existe pas, mais elles sont renvoyées par des points de terminaison différents. invalidMeetingId est utilisé par getMeetingInfo, isMeetingRunning, end et join. meetingNotFound est utilisé par sendChatMessage, getJoinUrl et learningDashboard.

duplicateWarning est un cas particulier : le returncode est SUCCESS, mais le messageKey signale qu’une réunion avec le même ID existe déjà. Votre application doit vérifier si les paramètres de la réunion existante correspondent à ce que vous aviez prévu. Si c’est le cas, vous pouvez continuer en toute sécurité. Sinon, choisissez un ID de réunion différent.

Les causes les plus courantes sont : utilisation du mauvais secret partagé, application d’un mauvais algorithme de hachage, encodage URL incohérent de la chaîne de requête, ou inclusion du paramètre checksum lui-même dans l’entrée du hachage. Assurez-vous que la chaîne que vous hachez est construite ainsi : apiMethodName + queryString + sharedSecret, où queryString n’inclut pas le paramètre checksum.

Cette erreur est renvoyée lorsqu’une requête POST n’a pas l’en-tête Content-Type ou utilise un type de contenu non pris en charge par BigBlueButton. Assurez-vous que vos requêtes POST incluent l’en-tête Content-Type: application/x-www-form-urlencoded.

BigBlueButton peut renvoyer des codes d’erreur supplémentaires provenant de plugins ou de modules personnalisés qui ne font pas partie de l’API de base. Les codes listés ici couvrent l’API principale BigBlueButton 3.0. Si vous rencontrez un messageKey non reconnu, consultez les journaux du serveur et les plugins installés pour plus d’informations.