API-version: 4.x seneste 3.x

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.

Kapitel 23

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

Fejlkoderne i denne reference er hentet direkte fra kildekoden til 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.

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.

Alle tre angiver, at det ønskede møde ikke er tilgængeligt, men de returneres af forskellige endpoints. 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.

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 anmodning med en brødtekst mangler headeren 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.

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