Chapter 23

API Error Reference

Every failed BigBlueButton API request returns a standardized XML error response. This chapter provides a complete reference of all 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>

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
invalidPassword The supplied password is invalid. join, end
guestDeniedAccess Access denied based on the guest policy. join
missingToken The session token is missing. getJoinUrl, learningDashboard
missingSession The session token is invalid. getJoinUrl, learningDashboard
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
invalidMeetingId The specified meeting ID does not exist. getMeetingInfo, isMeetingRunning, end, join
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, getJoinUrl, learningDashboard

Parameter Validation Errors

These errors are returned when required parameters are missing or when request data fails validation:

messageKey Message Triggering Endpoints
MissingParam Required parameter {param} is missing (dynamic). create, join, end, getMeetingInfo, and others
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, end, getMeetingInfo, insertDocument, sendChatMessage
emptyError The field must not be empty. General validation
fileNameError The file name could not be decoded. insertDocument

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. 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)
configNotFound No configuration found for this token. Internal validation
noConfigFound No configuration found for this request. Internal validation

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.

— the most common error is checsumError. 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 (MissingParam, missingParamMeetingID, etc.) indicate that a required field was not included in the request.

Confirm meeting state — errors like invalidMeetingId or meetingForciblyEnded 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.

Both indicate that the requested meeting does not exist, but they are returned by different endpoints. invalidMeetingId is used by getMeetingInfo, isMeetingRunning, end, and join. meetingNotFound is used by sendChatMessage, getJoinUrl, and learningDashboard.

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 POST request is missing the Content-Type header or uses a content type that BigBlueButton does not support. Ensure your POST requests include the Content-Type: application/x-www-form-urlencoded header.

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.