Версия 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 Сообщение Конечные точки, вызывающие ошибку
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.

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