Довідник помилок 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>Для помилок значення returncode завжди дорівнює FAILED. Єдиний виняток — duplicateWarning, який повертає SUCCESS, але містить ключ попереджувального повідомлення. Ваша інтеграція завжди повинна перевіряти поле messageKey, а не лише код результату.
Помилки автентифікації та авторизації
Ці помилки виникають, коли запит неможливо автентифікувати або коли викликач не має потрібних дозволів:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
checksumError | checksum не збігається. | Усі ендпоїнти |
invalidPassword | Наданий пароль недійсний. | join, end |
guestDeniedAccess | Доступ заборонено відповідно до гостьової політики. | join |
missingToken | Відсутній токен сесії. | getJoinUrl, learningDashboard |
missingSession | Токен сесії недійсний. | getJoinUrl, learningDashboard |
apiNotEnabled | Службу API не ввімкнено на цьому сервері. | Усі ендпоїнти |
Помилки керування зустрічами
Ці помилки стосуються створення, приєднання та керування зустрічами:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
invalidMeetingId | Указаний ID зустрічі не існує. | getMeetingInfo, isMeetingRunning, end, join |
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, getJoinUrl, learningDashboard |
Помилки перевірки параметрів
Ці помилки повертаються, коли обов’язкові параметри відсутні або коли дані запиту не проходять перевірку:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
MissingParam | Обов’язковий параметр {param} відсутній (динамічно). | create, join, end, getMeetingInfo, та інші |
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, end, getMeetingInfo, insertDocument, sendChatMessage |
emptyError | Поле не повинно бути порожнім. | Загальна перевірка |
fileNameError | Не вдалося декодувати ім’я файлу. | insertDocument |
Помилки запису
Ці помилки стосуються керування записами та операцій із текстовими доріжками:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
notFound | Записів не знайдено. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Для вказаного ID запису запис не знайдено. | putRecordingTextTrack |
empty_uploaded_text_track | Завантажений файл текстової доріжки порожній. | putRecordingTextTrack |
paramError | Параметр {paramName} відсутній (динамічно). | putRecordingTextTrack |
invalidKind | Недійсний параметр kind — очікується: subtitles або captions. | putRecordingTextTrack |
invalidLang | Недійсний параметр language. | putRecordingTextTrack |
Помилки сесії та користувача
Ці помилки виникають під час перевірки сесії та користувача:
messageKey | Повідомлення | Endpoint-и, що спричиняють помилку |
|---|---|---|
userNotFound | Для вказаного ID користувача не знайдено активної сесії. | join (з existingUserID) |
configNotFound | Для цього токена не знайдено конфігурації. | Внутрішня перевірка |
noConfigFound | Для цього запиту не знайдено конфігурації. | Внутрішня перевірка |
Усунення несправностей
Коли ви стикаєтеся з помилкою API, виконайте такі кроки, щоб діагностувати та вирішити проблему:
Перевірте messageKey — скористайтеся наведеними вище таблицями кодів помилок, щоб визначити точну причину збою та те, яка кінцева точка його спричинила.
checsumError. Ще раз переконайтеся, що ви використовуєте правильний спільний секрет, правильний алгоритм хешування і що рядок запиту точно збігається.
Перевірте обов’язкові параметри — помилки відсутніх параметрів (MissingParam, missingParamMeetingID тощо) вказують на те, що обов’язкове поле не було включене до запиту.
Підтвердьте стан зустрічі — помилки на кшталт invalidMeetingId або meetingForciblyEnded означають, що зустріч не існує або вже завершилася. Використовуйте 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, а не рядок повідомлення.invalidMeetingId використовується в getMeetingInfo, isMeetingRunning, end і join. meetingNotFound використовується в sendChatMessage, getJoinUrl і learningDashboard.duplicateWarning — це особливий випадок: returncode має значення SUCCESS, але messageKey сигналізує, що зустріч із таким самим ID уже існує. Ваш застосунок має перевірити, чи збігаються параметри наявної зустрічі з тими, які ви мали на увазі. Якщо так, можна безпечно продовжувати. Якщо ні, виберіть інший ID зустрічі.спільного секрету, застосування неправильного алгоритму хешування, непослідовне URL-кодування рядка запиту або включення самого параметра checksum до вхідних даних хешу. Переконайтеся, що рядок для хешування формується так: apiMethodName + queryString + sharedSecret, де queryString не містить параметра checksum.POST відсутній заголовок Content-Type або використовується тип вмісту, який BigBlueButton не підтримує. Переконайтеся, що ваші запити POST містять заголовок Content-Type: application/x-www-form-urlencoded.messageKey, перевірте журнали сервера та всі встановлені плагіни для отримання додаткової інформації.