API version: 4.x latest 3.x

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.

Chapter 23

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

The error codes listed in this reference are extracted directly from the 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.

Yes. While the 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.

All three indicate that the requested meeting is not available, but they are returned by different endpoints. 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>.

The 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.

The most common causes are: using the wrong 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.

This error is returned when a request with a body is missing the 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.

BigBlueButton may return additional error codes from plugins or custom modules that are not part of the core API. The codes listed here cover the core BigBlueButton 3.0 API. If you encounter an unrecognized messageKey, check the server logs and any installed plugins for more information.