You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.
API Error Reference
Failed BigBlueButton API requests return a standardized XML error response. This chapter provides a reference of the error codes and messages the API can return, based on source-code analysis of BigBlueButton 3.0.
Error Response Format
When an API call fails, BigBlueButton returns an XML response with three key elements: a returncode, a machine-readable messageKey, and a human-readable message. Every error response follows this structure:
<response>
<returncode>FAILED</returncode>
<messageKey>errorKeyHere</messageKey>
<message>A human-readable description of the error.</message>
</response> Exceptions: nonUniqueVoiceBridge and clientSettingsOverrideValidationError are returned as an errors list with key and message elements instead of messageKey and message. The session-based endpoints getJoinUrl, learningDashboard and stuns answer errors in JSON with a message but without a messageKey.
The returncode is always FAILED for errors. The only exception is duplicateWarning, which returns SUCCESS but includes a warning message key. Your integration should always check the messageKey field, not just the return code.
Authentication and Authorization Errors
These errors occur when a request cannot be authenticated or when the caller lacks the required permissions:
messageKey | Message | Triggering Endpoints |
|---|---|---|
checksumError | The checksum does not match. | All endpoints that require a checksum |
invalidPassword | The supplied password is invalid. | create, join, end |
guestDeniedAccess | Access denied based on the guest policy. | join |
apiNotEnabled | The API service is not enabled on this server. | All endpoints |
Meeting Management Errors
These errors relate to creating, joining, and managing meetings:
messageKey | Message | Triggering Endpoints |
|---|---|---|
notFound | A meeting with this ID does not exist. | getMeetingInfo, end |
invalidMeetingIdentifier | A meeting with this ID does not exist. | join |
meetingForciblyEnded | Cannot join a meeting that has been forcibly ended. | join |
idNotUnique | A meeting with this ID already exists. | create |
nonUniqueVoiceBridge | The selected voice bridge is already in use. | create |
duplicateWarning | This conference already exists and may be running. returncode is SUCCESS | create |
mismatchCreateTimeParam | The createTime parameter does not match the current meeting. | join |
maxParticipantsReached | The maximum number of participants has been reached. | join |
parentMeetingIDMissing | No parentMeetingID specified for the breakout room. | create (breakout) |
parentMeetingDoesNotExist | No parent meeting found for the breakout room. | create (breakout) |
meetingNotFound | The meeting was not found. | sendChatMessage |
Params required | No valid role was sent, or the password matches neither the moderator nor the attendee password. | join |
clientSettingsOverrideValidationError | The client settings override contains unknown or malformed keys (only checked when clientSettingsOverrideStrictValidation is enabled). | create |
Parameter Validation Errors
These errors are returned when required parameters are missing or when request data fails validation:
messageKey | Message | Triggering Endpoints |
|---|---|---|
missingParamMeetingID | The meeting ID must be provided. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | The fullName must be provided. | join |
missingParamRecordID | The recording ID must be provided. | updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks |
missingParamPublish | The publish value (true/false) must be provided. | publishRecordings |
validationError | General validation error (various messages). | Multiple endpoints |
unsupportedContentType | The Content-Type of the POST request is missing or unsupported. | create, join, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage |
emptyError | The field must not be empty. | General validation |
nullError | A required value is missing. | create, sendChatMessage |
sizeError | A parameter is outside its allowed length. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
Recording Errors
These errors are specific to recording management and text track operations:
messageKey | Message | Triggering Endpoints |
|---|---|---|
notFound | No recordings found. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | No recording found for the specified recording ID. | getRecordingTextTracks, putRecordingTextTrack |
empty_uploaded_text_track | The uploaded text track file is empty. | putRecordingTextTrack |
paramError | Parameter {paramName} is missing (dynamic). | putRecordingTextTrack |
invalidKind | Invalid kind parameter — expected: subtitles or captions. | putRecordingTextTrack |
invalidLang | Invalid language parameter. | putRecordingTextTrack |
Session and User Errors
These errors occur during session and user validation:
messageKey | Message | Triggering Endpoints |
|---|---|---|
userNotFound | No active session found for the specified user ID. | join (with existingUserID) |
Troubleshooting
When you encounter an API error, follow these steps to diagnose and resolve the issue:
Check the messageKey — use the error code tables above to identify the exact cause of the failure and which endpoint triggered it.
Verify your checksum — the most common error is checksumError. Double-check that you are using the correct shared secret, the right hash algorithm, and that the query string matches exactly.
Inspect required parameters — missing parameter errors (missingParamMeetingID, missingParamFullName, etc.) indicate that a required field was not included in the request.
Confirm meeting state — errors like notFound or invalidMeetingIdentifier mean the meeting does not exist or has already ended. Use getMeetingInfo to verify the current state before retrying.
Review the server logs — if the error message is not specific enough, check the BigBlueButton server logs in /var/log/bigbluebutton/ for more detailed information.
Some error messages are dynamic and include the name or value of the problematic parameter. Always log the full XML response from the API to make debugging easier.
When handling the duplicateWarning message key, note that the returncode is SUCCESS, not FAILED. This is a special case where BigBlueButton signals that a meeting with the same ID already exists but returns the existing meeting data instead of raising an error.
Frequently Asked Questions
BigBlueButton 3.0 source code. The official BBB documentation does not include a complete error reference. The definitions are spread across several source files including ApiErrors.java, ApiController.groovy, and RecordingController.groovy.messageKey values tend to remain stable across versions, the human-readable message text may change. Always use the messageKey for programmatic error handling, not the message string.notFound is used by getMeetingInfo, end, invalidMeetingIdentifier by join, and meetingNotFound by sendChatMessage (also when the meeting exists but nobody has joined it). isMeetingRunning never fails for an unknown meeting; it returns <running>false</running>.duplicateWarning is a special case: the returncode is SUCCESS, but the messageKey signals that a meeting with the same ID already exists. Your application should check whether the existing meeting parameters match what you intended. If they do, you can safely proceed. If not, choose a different meeting ID.shared secret, applying the wrong hash algorithm, URL-encoding the query string inconsistently, or including the checksum parameter itself in the hash input. Make sure the string you hash is built as: apiMethodName + queryString + sharedSecret, where queryString does not include the checksum parameter.Content-Type header or uses a content type that BigBlueButton does not support for that endpoint. Use application/x-www-form-urlencoded for form parameters; create also accepts an XML body, and insertDocument accepts only application/xml or text/xml.messageKey, check the server logs and any installed plugins for more information.