Kapitel 23

API-Fehlerreferenz

Jede fehlgeschlagene API-Anfrage an BigBlueButton gibt eine standardisierte XML-Fehlerantwort zurück. Dieses Kapitel bietet eine vollständige Referenz aller Fehlercodes und Meldungen, die die API zurückgeben kann, basierend auf Quellcodeanalysen 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>

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
invalidPassword Das angegebene Passwort ist ungültig. join, end
guestDeniedAccess Zugriff aufgrund der guest policy verweigert. join
missingToken Das session token fehlt. getJoinUrl, learningDashboard
missingSession Das session token ist ungültig. getJoinUrl, learningDashboard
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
invalidMeetingId Die angegebene meeting ID existiert nicht. getMeetingInfo, isMeetingRunning, end, join
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, getJoinUrl, learningDashboard

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
MissingParam Erforderlicher Parameter {param} fehlt (dynamisch). create, join, end, getMeetingInfo, und andere
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, end, getMeetingInfo, insertDocument, sendChatMessage
emptyError Das Feld darf nicht leer sein. Allgemeine Validierung
fileNameError Der Dateiname konnte nicht decodiert werden. insertDocument

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. 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)
configNotFound Keine Konfiguration für dieses Token gefunden. Interne Validierung
noConfigFound Keine Konfiguration für diese Anfrage gefunden. Interne Validierung

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.

— der häufigste Fehler ist checsumError. Prüfen Sie sorgfältig, dass Sie das richtige shared secret, den richtigen Hash-Algorithmus verwenden und dass der Query-String exakt übereinstimmt.

Prüfen Sie erforderliche Parameter — Fehler wegen fehlender Parameter (MissingParam, missingParamMeetingID usw.) weisen darauf hin, dass ein erforderliches Feld in der Anfrage nicht enthalten war.

Bestätigen Sie den Meeting-Status — Fehler wie invalidMeetingId oder meetingForciblyEnded bedeuten, dass das Meeting nicht existiert oder bereits beendet wurde. Verwenden Sie getMeetingInfo, um den aktuellen Status vor einem erneuten Versuch zu überprüfen.

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 sind direkt aus dem Quellcode von BigBlueButton 3.0 extrahiert. Die offizielle BBB-Dokumentation enthält keine vollständige Fehlerreferenz. Die Definitionen sind über 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.

Beide bedeuten, dass das angeforderte Meeting nicht existiert, werden aber von unterschiedlichen Endpunkten zurückgegeben. invalidMeetingId wird von getMeetingInfo, isMeetingRunning, end und join verwendet. meetingNotFound wird von sendChatMessage, getJoinUrl und learningDashboard verwendet.

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 POST-Anfrage der Header Content-Type fehlt oder ein Content-Type verwendet wird, den BigBlueButton nicht unterstützt. Stellen Sie sicher, dass Ihre POST-Anfragen den Header Content-Type: application/x-www-form-urlencoded enthalten.

BigBlueButton kann zusätzliche Fehlercodes von Plugins oder benutzerdefinierten Modulen zurückgeben, die nicht Teil der Kern-API sind. Die hier aufgeführten Codes decken die Kern-API von BigBlueButton 3.0 ab. Wenn Sie auf einen unbekannten messageKey stoßen, prüfen Sie die Server-Logs und eventuell installierte Plugins für weitere Informationen.