Wersja API: 4.x najnowsza 3.x

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.

Rozdział 23

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

Kody błędów wymienione w tym zestawieniu pochodzą bezpośrednio z kodu źródłowego 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.

Tak. Chociaż wartości 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.

Wszystkie trzy wskazują, że żądane spotkanie jest niedostępne, ale są zwracane przez różne punkty końcowe. 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.

Najczęstsze przyczyny to: użycie niewłaściwego 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.

Ten błąd jest zwracany, gdy żądanie z treścią nie zawiera nagłówka 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.

BigBlueButton może zwracać dodatkowe kody błędów z wtyczek lub niestandardowych modułów, które nie należą do podstawowego API. Wymienione tutaj kody obejmują podstawowe API BigBlueButton 3.0. Jeśli napotkasz nierozpoznany messageKey, sprawdź dzienniki serwera i zainstalowane wtyczki, aby uzyskać więcej informacji.