Du ser API-dokumentationen til BigBlueButton 3.x. Den aktuelle version er BigBlueButton 4.x. Planlægger du en opgradering? Migreringsvejledningen viser alle de ændringer, dine API-kald kræver.
API-fejlreference
Mislykkede API-anmodninger til BigBlueButton returnerer et standardiseret XML-fejlsvar. Dette kapitel indeholder en oversigt over de fejlkoder og meddelelser, som API'et kan returnere, baseret på en analyse af kildekoden til BigBlueButton 3.0.
Format for fejlsvar
Når et API-kald fejler, returnerer BigBlueButton et XML-svar med tre nøgleelementer: en returncode, en maskinlæsbar messageKey og en menneskelæsbar message. Hvert fejlsvar følger denne struktur:
<response>
<returncode>FAILED</returncode>
<messageKey>errorKeyHere</messageKey>
<message>A human-readable description of the error.</message>
</response> Undtagelser: nonUniqueVoiceBridge og clientSettingsOverrideValidationError returneres som en errors-liste med elementerne key og message i stedet for messageKey og message. De sessionsbaserede endpoints getJoinUrl, learningDashboard og stuns returnerer fejl i JSON med message, men uden messageKey.
returncode er altid FAILED ved fejl. Den eneste undtagelse er duplicateWarning, som returnerer SUCCESS, men inkluderer en advarselsnøgle. Din integration bør altid kontrollere feltet messageKey, ikke kun returkoden.
Godkendelses- og autorisationsfejl
Disse fejl opstår, når en anmodning ikke kan godkendes, eller når kalderen mangler de nødvendige tilladelser:
messageKey | Meddelelse | Udløsende endpoints |
|---|---|---|
checksumError | checksum matcher ikke. | Alle endpoints, der kræver en kontrolsum |
invalidPassword | Den angivne adgangskode er ugyldig. | create, join, end |
guestDeniedAccess | Adgang nægtet baseret på guest policy. | join |
apiNotEnabled | API-tjenesten er ikke aktiveret på denne server. | Alle slutpunkter |
Fejl i mødeadministration
Disse fejl vedrører oprettelse, deltagelse og administration af møder:
messageKey | Meddelelse | Udløsende endpoints |
|---|---|---|
notFound | Et møde med dette ID findes ikke. | getMeetingInfo, end |
invalidMeetingIdentifier | Et møde med dette ID findes ikke. | join |
meetingForciblyEnded | Kan ikke deltage i et møde, der er blevet tvangsafsluttet. | join |
idNotUnique | Et møde med dette ID findes allerede. | create |
nonUniqueVoiceBridge | Den valgte voice bridge er allerede i brug. | create |
duplicateWarning | Denne konference findes allerede og kan være i gang. returncode er SUCCESS | create |
mismatchCreateTimeParam | Parameteren createTime matcher ikke det aktuelle møde. | join |
maxParticipantsReached | Det maksimale antal deltagere er nået. | join |
parentMeetingIDMissing | Ingen parentMeetingID angivet for breakout-rummet. | create (breakout) |
parentMeetingDoesNotExist | Intet overordnet møde fundet for breakout-rummet. | create (breakout) |
meetingNotFound | Mødet blev ikke fundet. | sendChatMessage |
Params required | Der blev ikke sendt en gyldig rolle, eller adgangskoden matcher hverken moderator- eller deltageradgangskoden. | join |
clientSettingsOverrideValidationError | Tilsidesættelsen af klientindstillingerne indeholder ukendte eller forkert formaterede nøgler (kontrolleres kun, når clientSettingsOverrideStrictValidation er aktiveret). | create |
Fejl ved parametervalidering
Disse fejl returneres, når påkrævede parametre mangler, eller når anmodningsdata ikke består valideringen:
messageKey | Meddelelse | Udløsende endpoints |
|---|---|---|
missingParamMeetingID | meeting ID skal angives. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | fullName skal angives. | join |
missingParamRecordID | recording ID skal angives. | updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks |
missingParamPublish | Værdien publish (true/false) skal angives. | publishRecordings |
validationError | Generel valideringsfejl (forskellige meddelelser). | Flere slutpunkter |
unsupportedContentType | Content-Type for POST-requesten mangler eller understøttes ikke. | create, join, isMeetingRunning, end, getMeetingInfo, getMeetings, getSessions, insertDocument, sendChatMessage |
emptyError | Feltet må ikke være tomt. | Generel validering |
nullError | En påkrævet værdi mangler. | create, sendChatMessage |
sizeError | En parameters længde ligger uden for det tilladte interval. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
Optagelsesfejl
Disse fejl er specifikke for administration af optagelser og tekstsporoperationer:
messageKey | Meddelelse | Udløsende endpoints |
|---|---|---|
notFound | Ingen optagelser fundet. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Ingen optagelse fundet for det angivne recording ID. | getRecordingTextTracks, putRecordingTextTrack |
empty_uploaded_text_track | Den uploadede text track-fil er tom. | putRecordingTextTrack |
paramError | Parameteren {paramName} mangler (dynamisk). | putRecordingTextTrack |
invalidKind | Ugyldig kind-parameter — forventet: subtitles eller captions. | putRecordingTextTrack |
invalidLang | Ugyldig sprogparameter. | putRecordingTextTrack |
Session- og brugerfejl
Disse fejl opstår under validering af session og bruger:
messageKey | Meddelelse | Udløsende endpoints |
|---|---|---|
userNotFound | Ingen aktiv session fundet for det angivne user ID. | join (med existingUserID) |
Fejlfinding
Når du støder på en API-fejl, skal du følge disse trin for at diagnosticere og løse problemet:
Tjek messageKey — brug fejlkodetabellerne ovenfor til at identificere den præcise årsag til fejlen, og hvilket endpoint der udløste den.
Kontrollér din kontrolsum — den mest almindelige fejl er checksumError. Dobbelttjek, at du bruger den korrekte delte hemmelighed og den rigtige hash-algoritme, og at forespørgselsstrengen stemmer nøjagtigt overens.
Kontrollér obligatoriske parametre — fejl om manglende parametre (missingParamMeetingID, missingParamFullName osv.) angiver, at et obligatorisk felt ikke var med i anmodningen.
Bekræft mødets status — fejl som notFound eller invalidMeetingIdentifier betyder, at mødet ikke findes eller allerede er afsluttet. Brug getMeetingInfo til at kontrollere den aktuelle status, før du prøver igen.
Gennemgå serverloggene — hvis fejlmeddelelsen ikke er specifik nok, så tjek BigBlueButton-serverloggene i /var/log/bigbluebutton/ for mere detaljeret information.
Nogle fejlmeddelelser er dynamiske og indeholder navnet eller værdien af den problematiske parameter. Log altid det fulde XML-svar fra API'et for at gøre fejlfinding lettere.
Når du håndterer message key'en duplicateWarning, skal du bemærke, at returncode er SUCCESS, ikke FAILED. Dette er et særligt tilfælde, hvor BigBlueButton signalerer, at et møde med samme ID allerede findes, men returnerer de eksisterende mødedata i stedet for at udløse en fejl.
Ofte stillede spørgsmål
BigBlueButton 3.0. Den officielle BBB-dokumentation indeholder ikke en komplet fejlreference. Definitionerne er fordelt på flere kildefiler, herunder ApiErrors.java, ApiController.groovy og RecordingController.groovy.messageKey har tendens til at forblive stabile på tværs af versioner, kan den menneskelæselige meddelelsestekst ændre sig. Brug altid messageKey til programmatisk fejlhåndtering, ikke meddelelsesstrengen.notFound bruges af getMeetingInfo, end, invalidMeetingIdentifier af join og meetingNotFound af sendChatMessage (også når mødet findes, men ingen har tilsluttet sig det). isMeetingRunning fejler aldrig ved et ukendt møde; det returnerer <running>false</running>.duplicateWarning er et særligt tilfælde: returncode er SUCCESS, men messageKey signalerer, at et møde med samme ID allerede findes. Din applikation bør kontrollere, om de eksisterende mødeparametre matcher det, du havde til hensigt. Hvis de gør, kan du trygt fortsætte. Hvis ikke, skal du vælge et andet meeting ID.shared secret, anvendelse af forkert hash-algoritme, inkonsekvent URL-encoding af query-strengen eller inkludering af selve parameteren checksum i hash-inputtet. Sørg for, at den streng, du hasher, bygges som: apiMethodName + queryString + sharedSecret, hvor queryString ikke inkluderer parameteren checksum.Content-Type eller bruger en indholdstype, som BigBlueButton ikke understøtter for det pågældende endpoint. Brug application/x-www-form-urlencoded til formularparametre; create accepterer også en XML-brødtekst, og insertDocument accepterer kun application/xml eller text/xml.messageKey, kan du finde flere oplysninger i serverloggene og eventuelle installerede plugins.