Вы просматриваете документацию 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 | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
checksumError | Значение checksum не совпадает. | Все конечные точки, требующие контрольной суммы |
invalidPassword | Указанный пароль недействителен. | create, join, end |
guestDeniedAccess | Доступ запрещён на основании guest policy. | join |
apiNotEnabled | Служба API не включена на этом сервере. | Все конечные точки |
Ошибки управления встречами
Эти ошибки связаны с созданием, присоединением и управлением встречами:
messageKey | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
notFound | Встреча с этим идентификатором не существует. | getMeetingInfo, end |
invalidMeetingIdentifier | Встреча с этим идентификатором не существует. | join |
meetingForciblyEnded | Невозможно присоединиться к встрече, которая была принудительно завершена. | join |
idNotUnique | Встреча с этим идентификатором уже существует. | create |
nonUniqueVoiceBridge | Выбранный voice bridge уже используется. | create |
duplicateWarning | Эта конференция уже существует и может быть запущена. returncode имеет значение SUCCESS | create |
mismatchCreateTimeParam | Параметр createTime не соответствует текущей встрече. | join |
maxParticipantsReached | Достигнуто максимальное количество участников. | join |
parentMeetingIDMissing | Для групповой комнаты не указан parentMeetingID. | create (breakout) |
parentMeetingDoesNotExist | Для breakout room родительская встреча не найдена. | create (breakout) |
meetingNotFound | Встреча не найдена. | sendChatMessage |
Params required | Не передана допустимая роль, либо пароль не совпадает ни с паролем модератора, ни с паролем участника. | join |
clientSettingsOverrideValidationError | Переопределение настроек клиента содержит неизвестные или некорректно сформированные ключи (проверяется только при включённом clientSettingsOverrideStrictValidation). | create |
Ошибки проверки параметров
Эти ошибки возвращаются, когда отсутствуют обязательные параметры или данные запроса не проходят проверку:
messageKey | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
missingParamMeetingID | Необходимо указать meeting ID. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | Необходимо указать fullName. | join |
missingParamRecordID | Необходимо указать recording 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 | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
notFound | Записи не найдены. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Для указанного recording ID запись не найдена. | getRecordingTextTracks, putRecordingTextTrack |
empty_uploaded_text_track | Загруженный файл text track пуст. | putRecordingTextTrack |
paramError | Параметр {paramName} отсутствует (динамический). | putRecordingTextTrack |
invalidKind | Недопустимый параметр kind — ожидается: subtitles или captions. | putRecordingTextTrack |
invalidLang | Недопустимый параметр language. | putRecordingTextTrack |
Ошибки сеанса и пользователя
Эти ошибки возникают во время проверки сеанса и пользователя:
messageKey | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
userNotFound | Для указанного user 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 уже существует. Ваше приложение должно проверить, совпадают ли параметры существующей встречи с тем, что вы намеревались создать. Если да, можно безопасно продолжать. Если нет, выберите другой meeting ID.shared secret, применяется неправильный алгоритм хеширования, строка запроса URL-кодируется непоследовательно или в данные для хеширования включается сам параметр checksum. Убедитесь, что строка для хеширования строится так: apiMethodName + queryString + sharedSecret, где queryString не включает параметр checksum.Content-Type или используется тип содержимого, который BigBlueButton не поддерживает для этой конечной точки. Используйте application/x-www-form-urlencoded для параметров формы; create также принимает тело в формате XML, а insertDocument принимает только application/xml или text/xml.messageKey, проверьте журналы сервера и установленные плагины для получения дополнительной информации.