Версія API: 4.x найновіша 3.x

Ви переглядаєте документацію API для BigBlueButton 3.x. Поточна версія — BigBlueButton 4.x. Плануєте оновлення? У посібнику з міграції наведено всі зміни, які потрібно внести у ваші виклики API.

Розділ 23

Довідник помилок 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.

BigBlueButton може повертати додаткові коди помилок із плагінів або спеціальних модулів, які не входять до основного API. Наведені тут коди охоплюють основний API BigBlueButton 3.0. Якщо ви натрапили на нерозпізнаний messageKey, перевірте журнали сервера та встановлені плагіни, щоб отримати додаткову інформацію.
Посібник з API BigBlueButton