Kapitel 23

API-fejlreference

Hver mislykket BigBlueButton API-request returnerer et standardiseret XML-fejlsvar. Dette kapitel giver en komplet reference over alle fejlkoder og meddelelser, som API'et kan returnere, baseret på kildekodeanalyse af 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>

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 slutpunkter
invalidPassword Den angivne adgangskode er ugyldig. join, end
guestDeniedAccess Adgang nægtet baseret på guest policy. join
missingToken session token mangler. getJoinUrl, learningDashboard
missingSession session token er ugyldig. getJoinUrl, learningDashboard
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
invalidMeetingId Det angivne meeting ID findes ikke. getMeetingInfo, isMeetingRunning, end, join
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, getJoinUrl, learningDashboard

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
MissingParam Påkrævet parameter {param} mangler (dynamisk). create, join, end, getMeetingInfo, og andre
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, end, getMeetingInfo, insertDocument, sendChatMessage
emptyError Feltet må ikke være tomt. Generel validering
fileNameError Filnavnet kunne ikke afkodes. insertDocument

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. 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)
configNotFound Ingen konfiguration fundet for dette token. Intern validering
noConfigFound Ingen konfiguration fundet for denne anmodning. Intern validering

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.

— den mest almindelige fejl er checsumError. Dobbelttjek, at du bruger den korrekte shared secret, den rigtige hash-algoritme, og at query-strengen matcher præcist.

Undersøg krævede parametre — fejl om manglende parametre (MissingParam, missingParamMeetingID osv.) angiver, at et påkrævet felt ikke blev inkluderet i anmodningen.

Bekræft mødets status — fejl som invalidMeetingId eller meetingForciblyEnded betyder, at mødet ikke findes eller allerede er afsluttet. Brug getMeetingInfo til at verificere 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

Fejlkoderne i denne reference er udtrukket direkte fra kildekoden i BigBlueButton 3.0. Den officielle BBB-dokumentation indeholder ikke en komplet fejlreference. Definitionerne er spredt over flere kildefiler, herunder ApiErrors.java, ApiController.groovy og RecordingController.groovy.

Ja. Selvom værdierne for 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.

Begge angiver, at det ønskede møde ikke findes, men de returneres af forskellige endpoints. invalidMeetingId bruges af getMeetingInfo, isMeetingRunning, end og join. meetingNotFound bruges af sendChatMessage, getJoinUrl og learningDashboard.

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.

De mest almindelige årsager er: brug af forkert 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.

Denne fejl returneres, når en POST-request mangler headeren Content-Type eller bruger en content type, som BigBlueButton ikke understøtter. Sørg for, at dine POST-requests inkluderer headeren Content-Type: application/x-www-form-urlencoded.

BigBlueButton kan returnere yderligere fejlkoder fra plugins eller brugerdefinerede moduler, som ikke er en del af kerne-API'et. Koderne her dækker kerne-API'et i BigBlueButton 3.0. Hvis du støder på en ukendt messageKey, så tjek serverloggene og eventuelle installerede plugins for mere information.