API-versie: 4.x nieuwste 3.x

Je bekijkt de API-documentatie voor BigBlueButton 3.x. De huidige versie is BigBlueButton 4.x. Plan je een upgrade? De migratiehandleiding vermeldt alle wijzigingen die je in je API-aanroepen moet aanbrengen.

Hoofdstuk 23

API-foutreferentie

Mislukte API-verzoeken aan BigBlueButton retourneren een gestandaardiseerd XML-foutantwoord. Dit hoofdstuk biedt een overzicht van de foutcodes en berichten die de API kan retourneren, op basis van een analyse van de broncode 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>

Uitzonderingen: nonUniqueVoiceBridge en clientSettingsOverrideValidationError worden geretourneerd als een errors-lijst met de elementen key en message in plaats van messageKey en message. De sessiegebaseerde eindpunten getJoinUrl, learningDashboard en stuns retourneren fouten in JSON met een message, maar zonder een messageKey.

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 eindpunten die een checksum vereisen
invalidPassword Het opgegeven wachtwoord is ongeldig. create, join, end
guestDeniedAccess Toegang geweigerd op basis van het gastbeleid. join
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
notFound Een vergadering met deze ID bestaat niet. getMeetingInfo, end
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
Params required Er is geen geldige rol verzonden, of het wachtwoord komt noch met het moderatorwachtwoord, noch met het deelnemerswachtwoord overeen. join
clientSettingsOverrideValidationError De overschrijving van de clientinstellingen bevat onbekende of onjuist gevormde sleutels (wordt alleen gecontroleerd wanneer clientSettingsOverrideStrictValidation is ingeschakeld). create

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
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, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage
emptyError Het veld mag niet leeg zijn. Algemene validatie
nullError Een vereiste waarde ontbreekt. create, sendChatMessage
sizeError De lengte van een parameter valt buiten de toegestane grenzen. create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage

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. getRecordingTextTracks, 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)

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.

Controleer je checksum — de meest voorkomende fout is checksumError. Controleer zorgvuldig of je de juiste gedeelde geheime sleutel en het juiste hash-algoritme gebruikt en of de querystring exact overeenkomt.

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

Controleer de vergaderstatus — fouten zoals notFound of invalidMeetingIdentifier betekenen dat de vergadering niet bestaat of al is beëindigd. Gebruik getMeetingInfo om de huidige status te controleren voordat je 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 documentatie van BBB 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.

Alle drie geven aan dat de opgevraagde vergadering niet beschikbaar is, maar ze worden door verschillende endpoints geretourneerd. notFound wordt gebruikt door getMeetingInfo, end, invalidMeetingIdentifier door join en meetingNotFound door sendChatMessage (ook wanneer de vergadering bestaat maar nog niemand eraan heeft deelgenomen). isMeetingRunning geeft nooit een fout voor een onbekende vergadering; het retourneert <running>false</running>.

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 bij een verzoek met een body de header Content-Type ontbreekt of wanneer het een inhoudstype gebruikt dat BigBlueButton voor dat endpoint niet ondersteunt. Gebruik application/x-www-form-urlencoded voor formulierparameters; create accepteert ook een XML-body en insertDocument accepteert alleen application/xml of text/xml.

BigBlueButton kan aanvullende foutcodes retourneren van plug-ins of aangepaste modules die geen deel uitmaken van de kern-API. De hier vermelde codes dekken de kern-API van BigBlueButton 3.0. Als je een onbekende messageKey tegenkomt, controleer dan de serverlogboeken en eventuele geïnstalleerde plug-ins voor meer informatie.