API-Version: 4.x neueste 3.x
Kapitel 24

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/ gibt 404 mit einem JSON-Body statt eines XML-Dokuments zurück.
  • Eine Anfrage mit mehr als 10,000 Parametern wird mit HTTP 500 beantwortet.
  • Eine CORS-Preflight-Anfrage ohne CORS-Konfiguration gibt 200 ohne Access-Control-*-Header zurück (zuvor 403).
  • Alle Antworten enthalten die Sicherheitsheader X-Frame-Options, X-Content-Type-Options, Referrer-Policy und X-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

Die in dieser Referenz aufgeführten Fehlercodes stammen direkt aus dem Quellcode von 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.

Ja. Während die Werte von 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.

Alle drei zeigen an, dass das angeforderte Meeting nicht verfügbar ist, werden jedoch von unterschiedlichen Endpunkten zurückgegeben. 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.

Die häufigsten Ursachen sind: Verwendung des falschen 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.

Dieser Fehler wird zurückgegeben, wenn bei einer Anfrage mit Body der Header 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.

BigBlueButton kann zusätzliche Fehlercodes von Plugins oder benutzerdefinierten Modulen zurückgeben, die nicht zur Kern-API gehören. Die hier aufgeführten Codes decken die Kern-API von BigBlueButton 4.0 ab. Wenn Sie auf einen unbekannten messageKey stoßen, prüfen Sie die Serverprotokolle und alle installierten Plugins auf weitere Informationen.