Ви переглядаєте документацію API для BigBlueButton 3.x. Поточна версія — BigBlueButton 4.x. Плануєте оновлення? У посібнику з міграції наведено всі зміни, які потрібно внести у ваші виклики API.
Довідник помилок API
Невдалі запити до API BigBlueButton повертають стандартизовану відповідь про помилку у форматі XML. Цей розділ містить довідник кодів і повідомлень про помилки, які може повертати API, на основі аналізу вихідного коду BigBlueButton 3.0.
Формат відповіді про помилку
Коли виклик API завершується помилкою, BigBlueButton повертає XML-відповідь із трьома ключовими елементами: returncode, машинозчитуваним messageKey і зрозумілим людині message. Кожна відповідь про помилку має таку структуру:
<response>
<returncode>FAILED</returncode>
<messageKey>errorKeyHere</messageKey>
<message>A human-readable description of the error.</message>
</response> Винятки: nonUniqueVoiceBridge і clientSettingsOverrideValidationError повертаються як список errors з елементами key і message замість messageKey і message. Кінцеві точки getJoinUrl, learningDashboard і stuns, що працюють на основі сеансів, повертають помилки у форматі JSON із message, але без messageKey.
Для помилок значення returncode завжди дорівнює FAILED. Єдиний виняток — duplicateWarning, який повертає SUCCESS, але містить ключ попереджувального повідомлення. Ваша інтеграція завжди повинна перевіряти поле messageKey, а не лише код результату.
Помилки автентифікації та авторизації
Ці помилки виникають, коли запит неможливо автентифікувати або коли викликач не має потрібних дозволів:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
checksumError | checksum не збігається. | Усі кінцеві точки, що вимагають контрольної суми |
invalidPassword | Наданий пароль недійсний. | create, join, end |
guestDeniedAccess | Доступ заборонено відповідно до гостьової політики. | join |
apiNotEnabled | Службу API не ввімкнено на цьому сервері. | Усі ендпоїнти |
Помилки керування зустрічами
Ці помилки стосуються створення, приєднання та керування зустрічами:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
notFound | Зустрічі з цим ID не існує. | getMeetingInfo, end |
invalidMeetingIdentifier | Зустрічі з цим ID не існує. | join |
meetingForciblyEnded | Неможливо приєднатися до зустрічі, яку було примусово завершено. | join |
idNotUnique | Зустріч із цим ID уже існує. | create |
nonUniqueVoiceBridge | Вибраний голосовий міст уже використовується. | create |
duplicateWarning | Ця конференція вже існує і, можливо, виконується. returncode має значення SUCCESS | create |
mismatchCreateTimeParam | Параметр createTime не відповідає поточній зустрічі. | join |
maxParticipantsReached | Досягнуто максимальної кількості учасників. | join |
parentMeetingIDMissing | Для кімнати для груп не вказано parentMeetingID. | create (breakout) |
parentMeetingDoesNotExist | Для кімнати для груп не знайдено батьківську зустріч. | create (breakout) |
meetingNotFound | Зустріч не знайдено. | sendChatMessage |
Params required | Не надіслано допустимої ролі, або пароль не збігається ні з паролем модератора, ні з паролем учасника. | join |
clientSettingsOverrideValidationError | Перевизначення налаштувань клієнта містить невідомі або неправильно сформовані ключі (перевіряється лише тоді, коли clientSettingsOverrideStrictValidation увімкнено). | create |
Помилки перевірки параметрів
Ці помилки повертаються, коли обов’язкові параметри відсутні або коли дані запиту не проходять перевірку:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
missingParamMeetingID | Потрібно вказати ID зустрічі. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | Потрібно вказати fullName. | join |
missingParamRecordID | Потрібно вказати ID запису. | updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks |
missingParamPublish | Потрібно вказати значення publish (true/false). | publishRecordings |
validationError | Загальна помилка перевірки (різні повідомлення). | Кілька ендпоїнтів |
unsupportedContentType | Content-Type запиту POST відсутній або не підтримується. | create, join, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage |
emptyError | Поле не повинно бути порожнім. | Загальна перевірка |
nullError | Відсутнє обов’язкове значення. | create, sendChatMessage |
sizeError | Довжина параметра виходить за допустимі межі. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
Помилки запису
Ці помилки стосуються керування записами та операцій із текстовими доріжками:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
notFound | Записів не знайдено. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Для вказаного ID запису запис не знайдено. | getRecordingTextTracks, putRecordingTextTrack |
empty_uploaded_text_track | Завантажений файл текстової доріжки порожній. | putRecordingTextTrack |
paramError | Параметр {paramName} відсутній (динамічно). | putRecordingTextTrack |
invalidKind | Недійсний параметр kind — очікується: subtitles або captions. | putRecordingTextTrack |
invalidLang | Недійсний параметр language. | putRecordingTextTrack |
Помилки сесії та користувача
Ці помилки виникають під час перевірки сесії та користувача:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
userNotFound | Для вказаного ID користувача не знайдено активної сесії. | join (з existingUserID) |
Усунення несправностей
Коли ви стикаєтеся з помилкою API, виконайте такі кроки, щоб діагностувати та вирішити проблему:
Перевірте messageKey — скористайтеся наведеними вище таблицями кодів помилок, щоб визначити точну причину збою та те, яка кінцева точка його спричинила.
Перевірте контрольну суму — найпоширеніша помилка — checksumError. Переконайтеся, що ви використовуєте правильний спільний секрет і правильний алгоритм хешування, а рядок запиту точно збігається.
Перевірте обов’язкові параметри — помилки відсутніх параметрів (missingParamMeetingID, missingParamFullName тощо) вказують на те, що обов’язкове поле не було включено до запиту.
Перевірте стан зустрічі — помилки на кшталт notFound або invalidMeetingIdentifier означають, що зустріч не існує або вже завершилася. Скористайтеся getMeetingInfo, щоб перевірити поточний стан перед повторною спробою.
Перегляньте журнали сервера — якщо повідомлення про помилку недостатньо конкретне, перевірте журнали сервера BigBlueButton у /var/log/bigbluebutton/ для детальнішої інформації.
Деякі повідомлення про помилки є динамічними та містять назву або значення проблемного параметра. Завжди записуйте повну XML-відповідь API, щоб полегшити налагодження.
Під час обробки ключа повідомлення duplicateWarning зверніть увагу, що returncode має значення SUCCESS, а не FAILED. Це особливий випадок, коли BigBlueButton повідомляє, що зустріч із таким самим ID уже існує, але повертає дані наявної зустрічі замість помилки.
Поширені запитання
BigBlueButton 3.0. Офіційна документація BBB не містить повного довідника помилок. Визначення розподілено між кількома файлами вихідного коду, зокрема ApiErrors.java, ApiController.groovy і RecordingController.groovy.messageKey зазвичай залишаються стабільними між версіями, зрозумілий людині текст повідомлення може змінюватися. Для програмної обробки помилок завжди використовуйте messageKey, а не рядок повідомлення.notFound використовується в getMeetingInfo, end, invalidMeetingIdentifier — у join, а meetingNotFound — у sendChatMessage (зокрема й тоді, коли зустріч існує, але до неї ще ніхто не приєднався). isMeetingRunning ніколи не повертає помилку для невідомої зустрічі; натомість повертається <running>false</running>.duplicateWarning — це особливий випадок: returncode має значення SUCCESS, але messageKey сигналізує, що зустріч із таким самим ID уже існує. Ваш застосунок має перевірити, чи збігаються параметри наявної зустрічі з тими, які ви мали на увазі. Якщо так, можна безпечно продовжувати. Якщо ні, виберіть інший ID зустрічі.спільного секрету, застосування неправильного алгоритму хешування, непослідовне URL-кодування рядка запиту або включення самого параметра checksum до вхідних даних хешу. Переконайтеся, що рядок для хешування формується так: apiMethodName + queryString + sharedSecret, де queryString не містить параметра checksum.Content-Type або використовується тип вмісту, який BigBlueButton не підтримує для цієї кінцевої точки. Для параметрів форми використовуйте application/x-www-form-urlencoded; create також приймає тіло XML, а insertDocument приймає лише application/xml або text/xml.messageKey, перевірте журнали сервера та встановлені плагіни, щоб отримати додаткову інформацію.