Sie sehen die API-Dokumentation für BigBlueButton 3.x. Die aktuelle Version ist BigBlueButton 4.x. Planen Sie ein Upgrade? Der Migrationsleitfaden listet alle erforderlichen Änderungen an Ihren API-Aufrufen auf.
API-Fehlerreferenz
Fehlgeschlagene API-Anfragen an BigBlueButton geben eine standardisierte XML-Fehlerantwort zurück. Dieses Kapitel enthält eine Referenz der Fehlercodes und Meldungen, die die API zurückgeben kann, basierend auf einer Quellcodeanalyse von BigBlueButton 3.0.
Format der Fehlerantwort
Wenn ein API-Aufruf fehlschlägt, gibt BigBlueButton eine XML-Antwort mit drei Schlüsselelementen zurück: einem returncode, einem maschinenlesbaren messageKey und einer menschenlesbaren message. Jede Fehlerantwort folgt dieser Struktur:
<response>
<returncode>FAILED</returncode>
<messageKey>errorKeyHere</messageKey>
<message>A human-readable description of the error.</message>
</response> Ausnahmen: nonUniqueVoiceBridge und clientSettingsOverrideValidationError werden als errors-Liste mit key- und message-Elementen statt mit messageKey und message zurückgegeben. Die sitzungsbasierten Endpunkte getJoinUrl, learningDashboard und stuns geben Fehler als JSON mit message, aber ohne messageKey zurück.
Der Wert returncode ist bei Fehlern immer FAILED. Die einzige Ausnahme ist duplicateWarning, das SUCCESS zurückgibt, aber einen Warnungs-Nachrichtenschlüssel enthält. Ihre Integration sollte immer das Feld messageKey prüfen, nicht nur den Rückgabecode.
Authentifizierungs- und Autorisierungsfehler
Diese Fehler treten auf, wenn eine Anfrage nicht authentifiziert werden kann oder wenn dem Aufrufer die erforderlichen Berechtigungen fehlen:
messageKey | Nachricht | Auslösende Endpunkte |
|---|---|---|
checksumError | Die checksum stimmt nicht überein. | Alle Endpunkte, die eine Prüfsumme erfordern |
invalidPassword | Das angegebene Passwort ist ungültig. | create, join, end |
guestDeniedAccess | Zugriff aufgrund der guest policy verweigert. | join |
apiNotEnabled | Der API-Dienst ist auf diesem Server nicht aktiviert. | Alle Endpunkte |
Fehler bei der Meetingverwaltung
Diese Fehler beziehen sich auf das Erstellen, Beitreten und Verwalten von Meetings:
messageKey | Nachricht | Auslösende Endpunkte |
|---|---|---|
notFound | Ein Meeting mit dieser ID existiert nicht. | getMeetingInfo, end |
invalidMeetingIdentifier | Ein Meeting mit dieser ID existiert nicht. | join |
meetingForciblyEnded | Einem Meeting, das zwangsweise beendet wurde, kann nicht beigetreten werden. | join |
idNotUnique | Ein Meeting mit dieser ID existiert bereits. | create |
nonUniqueVoiceBridge | Die ausgewählte voice bridge wird bereits verwendet. | create |
duplicateWarning | Diese Konferenz existiert bereits und läuft möglicherweise. returncode ist SUCCESS | create |
mismatchCreateTimeParam | Der Parameter createTime stimmt nicht mit dem aktuellen Meeting überein. | join |
maxParticipantsReached | Die maximale Teilnehmerzahl wurde erreicht. | join |
parentMeetingIDMissing | Für den Breakout-Raum wurde keine parentMeetingID angegeben. | create (breakout) |
parentMeetingDoesNotExist | Kein übergeordnetes Meeting für den breakout room gefunden. | create (breakout) |
meetingNotFound | Das Meeting wurde nicht gefunden. | sendChatMessage |
Params required | Es wurde keine gültige Rolle übermittelt, oder das Passwort stimmt weder mit dem Moderator- noch mit dem Teilnehmerpasswort überein. | join |
clientSettingsOverrideValidationError | Die Überschreibung der Client-Einstellungen enthält unbekannte oder fehlerhaft formatierte Schlüssel (wird nur geprüft, wenn clientSettingsOverrideStrictValidation aktiviert ist). | create |
Fehler bei der Parametervalidierung
Diese Fehler werden zurückgegeben, wenn erforderliche Parameter fehlen oder wenn Anfragedaten die Validierung nicht bestehen:
messageKey | Nachricht | Auslösende Endpunkte |
|---|---|---|
missingParamMeetingID | Die meeting ID muss angegeben werden. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | Der fullName muss angegeben werden. | join |
missingParamRecordID | Die recording ID muss angegeben werden. | updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks |
missingParamPublish | Der Wert publish (true/false) muss angegeben werden. | publishRecordings |
validationError | Allgemeiner Validierungsfehler (verschiedene Meldungen). | Mehrere Endpunkte |
unsupportedContentType | Der Content-Type der POST-Anfrage fehlt oder wird nicht unterstützt. | create, join, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage |
emptyError | Das Feld darf nicht leer sein. | Allgemeine Validierung |
nullError | Ein erforderlicher Wert fehlt. | create, sendChatMessage |
sizeError | Die Länge eines Parameters liegt außerhalb des zulässigen Bereichs. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
Fehler bei Aufzeichnungen
Diese Fehler sind spezifisch für die Verwaltung von Aufzeichnungen und Textspur-Operationen:
messageKey | Nachricht | Auslösende Endpunkte |
|---|---|---|
notFound | Keine Aufzeichnungen gefunden. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Keine Aufzeichnung für die angegebene recording ID gefunden. | getRecordingTextTracks, putRecordingTextTrack |
empty_uploaded_text_track | Die hochgeladene text track-Datei ist leer. | putRecordingTextTrack |
paramError | Parameter {paramName} fehlt (dynamisch). | putRecordingTextTrack |
invalidKind | Ungültiger Parameter kind — erwartet: subtitles oder captions. | putRecordingTextTrack |
invalidLang | Ungültiger Sprachparameter. | putRecordingTextTrack |
Sitzungs- und Benutzerfehler
Diese Fehler treten während der Validierung von Sitzungen und Benutzern auf:
messageKey | Nachricht | Auslösende Endpunkte |
|---|---|---|
userNotFound | Keine aktive Sitzung für die angegebene user ID gefunden. | join (mit existingUserID) |
Fehlerbehebung
Wenn Sie auf einen API-Fehler stoßen, befolgen Sie diese Schritte, um das Problem zu diagnostizieren und zu beheben:
Prüfen Sie den messageKey — verwenden Sie die obigen Fehlercodetabellen, um die genaue Ursache des Fehlers und den auslösenden Endpunkt zu identifizieren.
Überprüfen Sie Ihre Prüfsumme — der häufigste Fehler ist checksumError. Vergewissern Sie sich, dass Sie das richtige gemeinsame Geheimnis und den richtigen Hash-Algorithmus verwenden und dass der Query-String exakt übereinstimmt.
Überprüfen Sie die erforderlichen Parameter — Fehler wegen fehlender Parameter (missingParamMeetingID, missingParamFullName usw.) weisen darauf hin, dass ein Pflichtfeld in der Anfrage nicht enthalten war.
Überprüfen Sie den Meetingstatus — Fehler wie notFound oder invalidMeetingIdentifier bedeuten, dass das Meeting nicht existiert oder bereits beendet wurde. Verwenden Sie getMeetingInfo, um den aktuellen Status zu überprüfen, bevor Sie es erneut versuchen.
Prüfen Sie die Server-Logs — wenn die Fehlermeldung nicht spezifisch genug ist, sehen Sie in den BigBlueButton-Server-Logs in /var/log/bigbluebutton/ nach, um detailliertere Informationen zu erhalten.
Einige Fehlermeldungen sind dynamisch und enthalten den Namen oder Wert des problematischen Parameters. Protokollieren Sie immer die vollständige XML-Antwort der API, um das Debugging zu erleichtern.
Beim Umgang mit dem Message-Key duplicateWarning beachten Sie bitte, dass der returncode SUCCESS ist, nicht FAILED. Dies ist ein Sonderfall, bei dem BigBlueButton signalisiert, dass bereits ein Meeting mit derselben ID existiert, aber die bestehenden Meeting-Daten zurückgibt, anstatt einen Fehler auszulösen.
Häufig gestellte Fragen
BigBlueButton 3.0. Die offizielle BBB-Dokumentation enthält keine vollständige Fehlerreferenz. Die Definitionen sind auf mehrere Quelldateien verteilt, darunter ApiErrors.java, ApiController.groovy und RecordingController.groovy.messageKey versionsübergreifend tendenziell stabil bleiben, kann sich der menschenlesbare Meldungstext ändern. Verwenden Sie für die programmgesteuerte Fehlerbehandlung immer den messageKey, nicht den Meldungstext.notFound wird von getMeetingInfo, end verwendet, invalidMeetingIdentifier von join und meetingNotFound von sendChatMessage (auch wenn das Meeting existiert, aber noch niemand beigetreten ist). isMeetingRunning schlägt bei einem unbekannten Meeting niemals fehl, sondern gibt <running>false</running> zurück.duplicateWarning ist ein Sonderfall: Der returncode ist SUCCESS, aber der messageKey signalisiert, dass bereits ein Meeting mit derselben ID existiert. Ihre Anwendung sollte prüfen, ob die bestehenden Meeting-Parameter mit dem übereinstimmen, was Sie beabsichtigt haben. Falls ja, können Sie sicher fortfahren. Andernfalls wählen Sie eine andere Meeting-ID.shared secret, Anwendung des falschen Hash-Algorithmus, inkonsistente URL-Codierung des Query-Strings oder Einbeziehung des Parameters checksum selbst in die Hash-Eingabe. Stellen Sie sicher, dass die zu hashende Zeichenkette wie folgt aufgebaut ist: apiMethodName + queryString + sharedSecret, wobei queryString den Parameter checksum nicht enthält.Content-Type fehlt oder ein Inhaltstyp verwendet wird, den BigBlueButton für diesen Endpunkt nicht unterstützt. Verwenden Sie application/x-www-form-urlencoded für Formularparameter; create akzeptiert auch einen XML-Body, und insertDocument akzeptiert nur application/xml oder text/xml.messageKey stoßen, prüfen Sie die Serverprotokolle und alle installierten Plugins auf weitere Informationen.