Version de l’API: 4.x dernière version 3.x

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.

Chapitre 23

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

Les codes d’erreur répertoriés dans cette référence sont extraits directement du code source de 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.

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 trois indiquent que la réunion demandée n’est pas disponible, mais ils sont renvoyés par des points de terminaison différents. 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.

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 comportant un corps ne contient pas l’en-tête 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.

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 répertoriés ici couvrent l’API de base de BigBlueButton 3.0. Si vous rencontrez une valeur messageKey non reconnue, consultez les journaux du serveur et les éventuels plugins installés pour en savoir plus.