Hoofdstuk 23

API-foutreferentie

Elke mislukte BigBlueButton-API-request retourneert een gestandaardiseerde XML-foutresponse. Dit hoofdstuk biedt een volledig overzicht van alle foutcodes en meldingen die de API kan retourneren, gebaseerd op broncodeanalyse van BigBlueButton 3.0.

Foutresponsformaat

Wanneer een API-call mislukt, retourneert BigBlueButton een XML-response met drie belangrijke elementen: een returncode, een machineleesbare messageKey en een mensleesbare message. Elke foutresponse volgt deze structuur: 

<response>
  <returncode>FAILED</returncode>
  <messageKey>errorKeyHere</messageKey>
  <message>A human-readable description of the error.</message>
</response>

De returncode is bij fouten altijd FAILED. De enige uitzondering is duplicateWarning, die SUCCESS retourneert maar een waarschuwingssleutel in het bericht bevat. Je integratie moet altijd het veld messageKey controleren, niet alleen de returncode.

Authenticatie- en autorisatiefouten

Deze fouten treden op wanneer een aanvraag niet kan worden geauthenticeerd of wanneer de aanroeper niet over de vereiste rechten beschikt:

messageKey Bericht Endpoints die dit kunnen veroorzaken
checksumError De checksum komt niet overeen. Alle endpoints
invalidPassword Het opgegeven wachtwoord is ongeldig. join, end
guestDeniedAccess Toegang geweigerd op basis van het gastbeleid. join
missingToken De session token ontbreekt. getJoinUrl, learningDashboard
missingSession De session token is ongeldig. getJoinUrl, learningDashboard
apiNotEnabled De API-service is niet ingeschakeld op deze server. Alle endpoints

Fouten bij vergaderbeheer

Deze fouten hebben betrekking op het aanmaken, deelnemen aan en beheren van vergaderingen:

messageKey Bericht Endpoints die dit kunnen veroorzaken
invalidMeetingId De opgegeven meeting ID bestaat niet. getMeetingInfo, isMeetingRunning, end, join
invalidMeetingIdentifier Een vergadering met deze ID bestaat niet. join
meetingForciblyEnded Kan niet deelnemen aan een vergadering die geforceerd is beëindigd. join
idNotUnique Een vergadering met deze ID bestaat al. create
nonUniqueVoiceBridge De geselecteerde voice bridge is al in gebruik. create
duplicateWarning Deze conferentie bestaat al en is mogelijk actief. returncode is SUCCESS create
mismatchCreateTimeParam De parameter createTime komt niet overeen met de huidige vergadering. join
maxParticipantsReached Het maximumaantal deelnemers is bereikt. join
parentMeetingIDMissing Geen parentMeetingID opgegeven voor de breakout room. create (breakout)
parentMeetingDoesNotExist Geen bovenliggende vergadering gevonden voor de breakout room. create (breakout)
meetingNotFound De vergadering is niet gevonden. sendChatMessage, getJoinUrl, learningDashboard

Fouten bij parametervalidatie

Deze fouten worden geretourneerd wanneer vereiste parameters ontbreken of wanneer aanvraaggegevens de validatie niet doorstaan:

messageKey Bericht Endpoints die dit kunnen veroorzaken
MissingParam Vereiste parameter {param} ontbreekt (dynamisch). create, join, end, getMeetingInfo, en andere
missingParamMeetingID De meeting ID moet worden opgegeven. create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage
missingParamFullName De fullName moet worden opgegeven. join
missingParamRecordID De recording ID moet worden opgegeven. updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks
missingParamPublish De waarde publish (true/false) moet worden opgegeven. publishRecordings
validationError Algemene validatiefout (diverse berichten). Meerdere endpoints
unsupportedContentType De Content-Type van de POST-request ontbreekt of wordt niet ondersteund. create, join, end, getMeetingInfo, insertDocument, sendChatMessage
emptyError Het veld mag niet leeg zijn. Algemene validatie
fileNameError De bestandsnaam kon niet worden gedecodeerd. insertDocument

Opnamefouten

Deze fouten zijn specifiek voor opnamebeheer en teksttrackbewerkingen:

messageKey Bericht Endpoints die dit kunnen veroorzaken
notFound Geen opnamen gevonden. updateRecordings, publishRecordings, deleteRecordings
noRecordings Geen opname gevonden voor de opgegeven recording ID. putRecordingTextTrack
empty_uploaded_text_track Het geüploade text track-bestand is leeg. putRecordingTextTrack
paramError Parameter {paramName} ontbreekt (dynamisch). putRecordingTextTrack
invalidKind Ongeldige parameter kind — verwacht: subtitles of captions. putRecordingTextTrack
invalidLang Ongeldige taalparameter. putRecordingTextTrack

Sessie- en gebruikersfouten

Deze fouten treden op tijdens sessie- en gebruikersvalidatie:

messageKey Bericht Endpoints die dit kunnen veroorzaken
userNotFound Geen actieve sessie gevonden voor de opgegeven user ID. join (met existingUserID)
configNotFound Geen configuratie gevonden voor deze token. Interne validatie
noConfigFound Geen configuratie gevonden voor deze aanvraag. Interne validatie

Probleemoplossing

Wanneer u een API-fout tegenkomt, volgt u deze stappen om het probleem te diagnosticeren en op te lossen:

Controleer de messageKey — gebruik de bovenstaande tabellen met foutcodes om de exacte oorzaak van de fout vast te stellen en welk endpoint deze heeft veroorzaakt.

— de meest voorkomende fout is checsumError. Controleer nogmaals of je het juiste shared secret gebruikt, het juiste hash-algoritme en of de querystring exact overeenkomt.

Controleer verplichte parameters — fouten door ontbrekende parameters (MissingParam, missingParamMeetingID, enz.) geven aan dat een verplicht veld niet in het verzoek is opgenomen.

Bevestig de status van de vergadering — fouten zoals invalidMeetingId of meetingForciblyEnded betekenen dat de vergadering niet bestaat of al is beëindigd. Gebruik getMeetingInfo om de huidige status te controleren voordat u het opnieuw probeert.

Controleer de serverlogs — als de foutmelding niet specifiek genoeg is, bekijk dan de BigBlueButton-serverlogs in /var/log/bigbluebutton/ voor meer gedetailleerde informatie.

Sommige foutmeldingen zijn dynamisch en bevatten de naam of waarde van de problematische parameter. Log altijd de volledige XML-respons van de API om het debuggen te vergemakkelijken.

Houd er bij het afhandelen van de berichtsleutel duplicateWarning rekening mee dat de returncode SUCCESS is en niet FAILED. Dit is een speciaal geval waarbij BigBlueButton aangeeft dat er al een vergadering met dezelfde ID bestaat, maar de bestaande vergadergegevens retourneert in plaats van een fout te geven.

Veelgestelde vragen

De foutcodes in dit overzicht zijn rechtstreeks afkomstig uit de broncode van BigBlueButton 3.0. De officiële BBB-documentatie bevat geen volledig foutenoverzicht. De definities zijn verspreid over verschillende bronbestanden, waaronder ApiErrors.java, ApiController.groovy en RecordingController.groovy.

Ja. Hoewel de waarden van messageKey doorgaans stabiel blijven tussen versies, kan de mensleesbare meldingstekst veranderen. Gebruik voor programmatische foutafhandeling altijd de messageKey en niet de meldingsstring.

Beide geven aan dat de opgevraagde vergadering niet bestaat, maar ze worden door verschillende endpoints geretourneerd. invalidMeetingId wordt gebruikt door getMeetingInfo, isMeetingRunning, end en join. meetingNotFound wordt gebruikt door sendChatMessage, getJoinUrl en learningDashboard.

De duplicateWarning is een speciaal geval: de returncode is SUCCESS, maar de messageKey geeft aan dat er al een vergadering met dezelfde ID bestaat. Je applicatie moet controleren of de bestaande vergaderparameters overeenkomen met wat je bedoelde. Zo ja, dan kun je veilig doorgaan. Zo niet, kies dan een andere meeting-ID.

De meest voorkomende oorzaken zijn: het verkeerde shared secret gebruiken, het verkeerde hash-algoritme toepassen, de querystring inconsistent URL-encoden, of de parameter checksum zelf opnemen in de hash-invoer. Zorg ervoor dat de string die je hasht is opgebouwd als: apiMethodName + queryString + sharedSecret, waarbij queryString de parameter checksum niet bevat.

Deze fout wordt geretourneerd wanneer een POST-request de header Content-Type mist of een contenttype gebruikt dat BigBlueButton niet ondersteunt. Zorg ervoor dat je POST-requests de header Content-Type: application/x-www-form-urlencoded bevatten.

BigBlueButton kan aanvullende foutcodes retourneren vanuit plugins of aangepaste modules die geen deel uitmaken van de core-API. De hier vermelde codes dekken de core-BigBlueButton 3.0-API. Als je een niet-herkende messageKey tegenkomt, controleer dan de serverlogs en eventuele geïnstalleerde plugins voor meer informatie.