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 4.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.
Bei Fehlern ist returncode immer FAILED. Die einzigen Ausnahmen sind duplicateWarning und documentsDropped, die SUCCESS zurückgeben, aber einen Meldungsschlüssel für eine Warnung enthalten. 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 |
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, insertDocument |
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 |
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) |
Neue Fehlerschlüssel in BigBlueButton 4.0 BBB 4.0+
Die folgenden Meldungsschlüssel wurden in BBB 4.0 und 4.0.1 hinzugefügt. Integrationen, die messageKey auswerten, sollten sie explizit behandeln:
messageKey | Nachricht | Auslösende Endpunkte |
|---|---|---|
fullNameTooLong | fullName überschreitet 255 Zeichen. | join |
documentsDropped | Wird mit SUCCESS zurückgegeben: Es wurden mehr Dokumente als maxPresentationsPerRequest übermittelt; die überzähligen Dokumente wurden nicht hochgeladen. | create, insertDocument |
invalidPresentationUrl | Eine Dokument-URL entspricht nicht der gültigen URI-Syntax. | create, insertDocument |
rateLimitExceeded | Zu viele Aufrufe für diese Konferenz innerhalb des Zeitfensters (insertDocumentMaxRequests). | insertDocument |
malformedXml | Der Anfragetext ist kein wohlgeformtes XML. | create, insertDocument |
invalidFilename | Ein Dateiname ist ungültig oder kann nicht aus der URL abgeleitet werden. | insertDocument |
presentationDisabled | Die Präsentationsfunktion ist für die Konferenz deaktiviert. | insertDocument |
noDocuments | Die Anfrage enthält kein Dokument. | insertDocument |
missingParamMessage | Der Parameter message fehlt. | sendChatMessage |
Geänderte HTTP-Antworten
Die ersten drei Änderungen werden mit dem Upgrade auf Grails 8 eingeführt, das in BBB 3.0.40 bereits enthalten ist. Die Sicherheitsheader sind erst in BBB 4.0 standardmäßig aktiviert.
- Eine unbekannte URL unterhalb von
/bigbluebutton/gibt404mit einem JSON-Body statt eines XML-Dokuments zurück. - Eine Anfrage mit mehr als 10,000 Parametern wird mit
HTTP 500beantwortet. - Eine CORS-Preflight-Anfrage ohne CORS-Konfiguration gibt
200ohneAccess-Control-*-Header zurück (zuvor403). - Alle Antworten enthalten die Sicherheitsheader
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyundX-XSS-Protection.
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 4.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, insertDocument 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.