Informacje o błędach API
Każde nieudane żądanie API BigBlueButton zwraca ustandaryzowaną odpowiedź błędu XML. Ten rozdział zawiera kompletny opis wszystkich kodów i komunikatów błędów, jakie może zwrócić API, oparty 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>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 endpointy |
invalidPassword | Podane hasło jest nieprawidłowe. | join, end |
guestDeniedAccess | Odmowa dostępu na podstawie polityki gości. | join |
missingToken | Brakuje tokenu sesji. | getJoinUrl, learningDashboard |
missingSession | Token sesji jest nieprawidłowy. | getJoinUrl, learningDashboard |
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 |
|---|---|---|
invalidMeetingId | Podany identyfikator spotkania nie istnieje. | getMeetingInfo, isMeetingRunning, end, join |
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, getJoinUrl, learningDashboard |
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 |
|---|---|---|
MissingParam | Brakuje wymaganego parametru {param} (dynamiczne). | create, join, end, getMeetingInfo, i inne |
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, end, getMeetingInfo, insertDocument, sendChatMessage |
emptyError | Pole nie może być puste. | Walidacja ogólna |
fileNameError | Nie udało się zdekodować nazwy pliku. | insertDocument |
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. | 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) |
configNotFound | Nie znaleziono konfiguracji dla tego tokenu. | Walidacja wewnętrzna |
noConfigFound | Nie znaleziono konfiguracji dla tego żądania. | Walidacja wewnętrzna |
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ł.
checsumError. Upewnij się, że używasz poprawnego shared secret, właściwego algorytmu haszującego i że ciąg zapytania zgadza się dokładnie.
Sprawdź wymagane parametry — błędy brakujących parametrów (MissingParam, missingParamMeetingID itd.) wskazują, że wymagane pole nie zostało uwzględnione w żądaniu.
Potwierdź stan spotkania — błędy takie jak invalidMeetingId lub meetingForciblyEnded oznaczają, że spotkanie nie istnieje lub już się zakończyło. Użyj getMeetingInfo, aby zweryfikować bieżący 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 kompletnego opisu 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.invalidMeetingId jest używane przez getMeetingInfo, isMeetingRunning, end i join. meetingNotFound jest używane przez sendChatMessage, getJoinUrl i learningDashboard.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.POST nie zawiera nagłówka Content-Type lub używa typu treści, którego BigBlueButton nie obsługuje. Upewnij się, że Twoje żądania POST zawierają nagłówek Content-Type: application/x-www-form-urlencoded.messageKey, sprawdź logi serwera i wszelkie zainstalowane wtyczki, aby uzyskać więcej informacji.