Vous consultez la documentation de l’API pour BigBlueButton 3.x. La version actuelle est BigBlueButton 4.x. Vous prévoyez une mise à niveau ? Le guide de migration répertorie toutes les modifications à apporter à vos appels API.
Référence des erreurs de l’API
Les requêtes à l’API BigBlueButton qui échouent renvoient une réponse d’erreur XML standardisée. Ce chapitre fournit une référence des codes et messages d’erreur que l’API peut renvoyer, sur la base d’une 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> Exceptions : nonUniqueVoiceBridge et clientSettingsOverrideValidationError sont renvoyés sous forme de liste errors avec des éléments key et message au lieu de messageKey et message. Les points de terminaison basés sur une session getJoinUrl, learningDashboard et stuns renvoient les erreurs au format JSON avec un champ message, mais sans champ messageKey.
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 nécessitant une somme de contrôle |
invalidPassword | Le mot de passe fourni est invalide. | create, join, end |
guestDeniedAccess | Accès refusé selon la politique invité. | join |
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 |
|---|---|---|
notFound | Aucune réunion avec cet identifiant n'existe. | getMeetingInfo, end |
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 |
Params required | Aucun rôle valide n’a été envoyé, ou le mot de passe ne correspond ni à celui des modérateurs ni à celui des participants. | join |
clientSettingsOverrideValidationError | La configuration de remplacement des paramètres du client contient des clés inconnues ou mal formées (vérification effectuée uniquement lorsque clientSettingsOverrideStrictValidation est activé). | create |
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 |
|---|---|---|
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, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage |
emptyError | Le champ ne doit pas être vide. | Validation générale |
nullError | Une valeur obligatoire est manquante. | create, sendChatMessage |
sizeError | La longueur d’un paramètre ne respecte pas les limites autorisées. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
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é. | getRecordingTextTracks, 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) |
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é.
Vérifiez votre somme de contrôle — l’erreur la plus courante est checksumError. Vérifiez bien 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 obligatoires — les erreurs de paramètres manquants (missingParamMeetingID, missingParamFullName, etc.) indiquent qu’un champ obligatoire n’a pas été inclus dans la requête.
Confirmez l’état de la réunion — des erreurs telles que notFound ou invalidMeetingIdentifier 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
BigBlueButton 3.0. La documentation officielle de BBB ne comprend pas de référence complète des erreurs. Les définitions sont réparties dans plusieurs fichiers source, notamment ApiErrors.java, ApiController.groovy et RecordingController.groovy.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.notFound est utilisé par getMeetingInfo, end, invalidMeetingIdentifier par join et meetingNotFound par sendChatMessage (également lorsque la réunion existe, mais que personne ne l’a rejointe). isMeetingRunning n’échoue jamais pour une réunion inconnue ; il renvoie <running>false</running>.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.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.Content-Type ou utilise un type de contenu que BigBlueButton ne prend pas en charge pour ce point de terminaison. Utilisez application/x-www-form-urlencoded pour les paramètres de formulaire ; create accepte également un corps XML, et insertDocument accepte uniquement application/xml ou text/xml.messageKey non reconnue, consultez les journaux du serveur et les éventuels plugins installés pour en savoir plus.