Przeglądasz dokumentację API dla BigBlueButton 3.x. Aktualna wersja to BigBlueButton 4.x. Planujesz aktualizację? Przewodnik migracji zawiera wszystkie zmiany wymagane w wywołaniach API.
Informacje o błędach API
Nieudane żądania do API BigBlueButton zwracają standardową odpowiedź błędu w formacie XML. Ten rozdział zawiera zestawienie kodów błędów i komunikatów, które API może zwrócić, oparte na analizie kodu źródłowego BigBlueButton 3.0.
Format odpowiedzi błędu
Gdy wywołanie API kończy się niepowodzeniem, BigBlueButton zwraca odpowiedź XML z trzema kluczowymi elementami: returncode, odczytywalnym maszynowo messageKey oraz czytelnym dla człowieka message. Każda odpowiedź błędu ma następującą strukturę:
<response>
<returncode>FAILED</returncode>
<messageKey>errorKeyHere</messageKey>
<message>A human-readable description of the error.</message>
</response> Wyjątki: nonUniqueVoiceBridge i clientSettingsOverrideValidationError są zwracane jako lista errors z elementami key i message zamiast messageKey i message. Punkty końcowe oparte na sesjach getJoinUrl, learningDashboard i stuns zwracają błędy w formacie JSON z polem message, ale bez pola messageKey.
returncode ma zawsze wartość FAILED w przypadku błędów. Jedynym wyjątkiem jest duplicateWarning, który zwraca SUCCESS, ale zawiera klucz komunikatu ostrzeżenia. Twoja integracja powinna zawsze sprawdzać pole messageKey, a nie tylko kod zwrotny.
Błędy uwierzytelniania i autoryzacji
Te błędy występują, gdy żądanie nie może zostać uwierzytelnione lub gdy wywołujący nie ma wymaganych uprawnień:
messageKey | Komunikat | Endpointy wywołujące |
|---|---|---|
checksumError | Parametr checksum nie zgadza się. | Wszystkie punkty końcowe wymagające sumy kontrolnej |
invalidPassword | Podane hasło jest nieprawidłowe. | create, join, end |
guestDeniedAccess | Odmowa dostępu na podstawie polityki gości. | join |
apiNotEnabled | Usługa API nie jest włączona na tym serwerze. | Wszystkie endpointy |
Błędy zarządzania spotkaniami
Te błędy dotyczą tworzenia, dołączania i zarządzania spotkaniami:
messageKey | Komunikat | Endpointy wywołujące |
|---|---|---|
notFound | Spotkanie o tym ID nie istnieje. | getMeetingInfo, end |
invalidMeetingIdentifier | Spotkanie o tym ID nie istnieje. | join |
meetingForciblyEnded | Nie można dołączyć do spotkania, które zostało wymuszenie zakończone. | join |
idNotUnique | Spotkanie o tym ID już istnieje. | create |
nonUniqueVoiceBridge | Wybrany mostek głosowy jest już używany. | create |
duplicateWarning | Ta konferencja już istnieje i może być uruchomiona. returncode ma wartość SUCCESS | create |
mismatchCreateTimeParam | Parametr createTime nie odpowiada bieżącemu spotkaniu. | join |
maxParticipantsReached | Osiągnięto maksymalną liczbę uczestników. | join |
parentMeetingIDMissing | Nie podano parentMeetingID dla pokoju breakout. | create (breakout) |
parentMeetingDoesNotExist | Nie znaleziono spotkania nadrzędnego dla pokoju breakout. | create (breakout) |
meetingNotFound | Nie znaleziono spotkania. | sendChatMessage |
Params required | Nie przesłano prawidłowej roli lub hasło nie jest zgodne ani z hasłem moderatora, ani z hasłem uczestnika. | join |
clientSettingsOverrideValidationError | Nadpisanie ustawień klienta zawiera nieznane lub nieprawidłowo sformatowane klucze (sprawdzane tylko wtedy, gdy włączono clientSettingsOverrideStrictValidation). | create |
Błędy walidacji parametrów
Te błędy są zwracane, gdy brakuje wymaganych parametrów lub gdy dane żądania nie przechodzą walidacji:
messageKey | Komunikat | Endpointy wywołujące |
|---|---|---|
missingParamMeetingID | Należy podać identyfikator spotkania. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | Należy podać fullName. | join |
missingParamRecordID | Należy podać identyfikator nagrania. | updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks |
missingParamPublish | Należy podać wartość publish (true/false). | publishRecordings |
validationError | Ogólny błąd walidacji (różne komunikaty). | Wiele endpointów |
unsupportedContentType | Brakuje Content-Type żądania POST lub jest on nieobsługiwany. | create, join, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage |
emptyError | Pole nie może być puste. | Walidacja ogólna |
nullError | Brakuje wymaganej wartości. | create, sendChatMessage |
sizeError | Długość parametru wykracza poza dozwolony zakres. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
Błędy nagrywania
Te błędy są specyficzne dla zarządzania nagraniami i operacji na ścieżkach tekstowych:
messageKey | Komunikat | Endpointy wywołujące |
|---|---|---|
notFound | Nie znaleziono nagrań. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Nie znaleziono nagrania dla podanego identyfikatora nagrania. | getRecordingTextTracks, putRecordingTextTrack |
empty_uploaded_text_track | Przesłany plik ścieżki tekstowej jest pusty. | putRecordingTextTrack |
paramError | Brakuje parametru {paramName} (dynamiczne). | putRecordingTextTrack |
invalidKind | Nieprawidłowy parametr kind — oczekiwano: subtitles lub captions. | putRecordingTextTrack |
invalidLang | Nieprawidłowy parametr language. | putRecordingTextTrack |
Błędy sesji i użytkownika
Te błędy występują podczas walidacji sesji i użytkownika:
messageKey | Komunikat | Endpointy wywołujące |
|---|---|---|
userNotFound | Nie znaleziono aktywnej sesji dla podanego identyfikatora użytkownika. | join (z existingUserID) |
Rozwiązywanie problemów
Gdy napotkasz błąd API, wykonaj następujące kroki, aby zdiagnozować i rozwiązać problem:
Sprawdź messageKey — użyj powyższych tabel kodów błędów, aby ustalić dokładną przyczynę niepowodzenia i endpoint, który je wywołał.
Sprawdź sumę kontrolną — najczęstszym błędem jest checksumError. Upewnij się, że używasz prawidłowego współdzielonego klucza tajnego i właściwego algorytmu haszującego oraz że ciąg zapytania jest dokładnie zgodny.
Sprawdź wymagane parametry — błędy brakujących parametrów (missingParamMeetingID, missingParamFullName itp.) wskazują, że w żądaniu nie uwzględniono wymaganego pola.
Potwierdź stan spotkania — błędy takie jak notFound lub invalidMeetingIdentifier oznaczają, że spotkanie nie istnieje lub już się zakończyło. Użyj getMeetingInfo, aby sprawdzić aktualny stan przed ponowną próbą.
Przejrzyj logi serwera — jeśli komunikat błędu nie jest wystarczająco precyzyjny, sprawdź logi serwera BigBlueButton w /var/log/bigbluebutton/, aby uzyskać bardziej szczegółowe informacje.
Niektóre komunikaty o błędach są dynamiczne i zawierają nazwę lub wartość problematycznego parametru. Zawsze zapisuj pełną odpowiedź XML z API, aby ułatwić debugowanie.
Przy obsłudze klucza komunikatu duplicateWarning należy pamiętać, że returncode ma wartość SUCCESS, a nie FAILED. Jest to szczególny przypadek, w którym BigBlueButton sygnalizuje, że spotkanie o tym samym ID już istnieje, ale zwraca dane istniejącego spotkania zamiast zgłaszać błąd.
Najczęściej zadawane pytania
BigBlueButton 3.0. Oficjalna dokumentacja BBB nie zawiera pełnego zestawienia błędów. Definicje są rozproszone w kilku plikach źródłowych, w tym ApiErrors.java, ApiController.groovy i RecordingController.groovy.messageKey zwykle pozostają stabilne między wersjami, tekst komunikatu czytelny dla człowieka może się zmieniać. Do programistycznej obsługi błędów zawsze używaj messageKey, a nie tekstu komunikatu.notFound jest używany przez getMeetingInfo, end, invalidMeetingIdentifier przez join, a meetingNotFound przez sendChatMessage (również wtedy, gdy spotkanie istnieje, ale nikt do niego nie dołączył). isMeetingRunning nigdy nie zwraca błędu dla nieznanego spotkania; zwraca <running>false</running>.duplicateWarning to szczególny przypadek: returncode ma wartość SUCCESS, ale messageKey sygnalizuje, że spotkanie o tym samym ID już istnieje. Twoja aplikacja powinna sprawdzić, czy parametry istniejącego spotkania odpowiadają temu, co było zamierzone. Jeśli tak, można bezpiecznie kontynuować. Jeśli nie, wybierz inny identyfikator spotkania.shared secret, zastosowanie niewłaściwego algorytmu haszującego, niespójne kodowanie URL ciągu zapytania lub uwzględnienie samego parametru checksum w danych wejściowych hasha. Upewnij się, że haszowany ciąg jest budowany jako: apiMethodName + queryString + sharedSecret, gdzie queryString nie zawiera parametru checksum.Content-Type lub używa typu treści, którego BigBlueButton nie obsługuje dla danego punktu końcowego. Dla parametrów formularza użyj application/x-www-form-urlencoded; create akceptuje również treść XML, a insertDocument akceptuje wyłącznie application/xml lub text/xml.messageKey, sprawdź dzienniki serwera i zainstalowane wtyczki, aby uzyskać więcej informacji.