Справочник ошибок 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 | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
checksumError | Значение checksum не совпадает. | Все конечные точки |
invalidPassword | Указанный пароль недействителен. | join, end |
guestDeniedAccess | Доступ запрещён на основании guest policy. | join |
missingToken | Отсутствует session token. | getJoinUrl, learningDashboard |
missingSession | Недействительный session token. | getJoinUrl, learningDashboard |
apiNotEnabled | Служба API не включена на этом сервере. | Все конечные точки |
Ошибки управления встречами
Эти ошибки связаны с созданием, присоединением и управлением встречами:
messageKey | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
invalidMeetingId | Указанный meeting ID не существует. | getMeetingInfo, isMeetingRunning, end, join |
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, getJoinUrl, learningDashboard |
Ошибки проверки параметров
Эти ошибки возвращаются, когда отсутствуют обязательные параметры или данные запроса не проходят проверку:
messageKey | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
MissingParam | Отсутствует обязательный параметр {param} (динамический). | create, join, end, getMeetingInfo, и другие |
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, end, getMeetingInfo, insertDocument, sendChatMessage |
emptyError | Поле не должно быть пустым. | Общая проверка |
fileNameError | Не удалось декодировать имя файла. | insertDocument |
Ошибки записи
Эти ошибки относятся к управлению записями и операциям с текстовыми дорожками:
messageKey | Сообщение | Конечные точки, вызывающие ошибку |
|---|---|---|
notFound | Записи не найдены. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Для указанного recording ID запись не найдена. | 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) |
configNotFound | Для этого токена конфигурация не найдена. | Внутренняя проверка |
noConfigFound | Для этого запроса конфигурация не найдена. | Внутренняя проверка |
Устранение неполадок
При возникновении ошибки API выполните следующие шаги, чтобы диагностировать и устранить проблему:
Проверьте messageKey — используйте приведённые выше таблицы кодов ошибок, чтобы определить точную причину сбоя и то, какой эндпоинт его вызвал.
checsumError. Ещё раз убедитесь, что вы используете правильный shared secret, верный алгоритм хеширования и что строка запроса точно совпадает.
Проверьте обязательные параметры — ошибки отсутствующих параметров (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 уже существует. Ваше приложение должно проверить, совпадают ли параметры существующей встречи с тем, что вы намеревались создать. Если да, можно безопасно продолжать. Если нет, выберите другой meeting ID.shared secret, применяется неправильный алгоритм хеширования, строка запроса URL-кодируется непоследовательно или в данные для хеширования включается сам параметр checksum. Убедитесь, что строка для хеширования строится так: apiMethodName + queryString + sharedSecret, где queryString не включает параметр checksum.POST отсутствует заголовок Content-Type или используется тип содержимого, который BigBlueButton не поддерживает. Убедитесь, что ваши запросы POST включают заголовок Content-Type: application/x-www-form-urlencoded.messageKey, проверьте журналы сервера и установленные плагины для получения дополнительной информации.