Capitolo 23

Riferimento errori API

Ogni richiesta API BigBlueButton non riuscita restituisce una risposta di errore XML standardizzata. Questo capitolo fornisce un riferimento completo di tutti i codici e messaggi di errore che l'API può restituire, basato sull'analisi del codice sorgente di BigBlueButton 3.0.

Formato della risposta di errore

Quando una chiamata API fallisce, BigBlueButton restituisce una risposta XML con tre elementi chiave: un returncode, un messageKey leggibile dalla macchina e un message leggibile dall'uomo. Ogni risposta di errore segue questa struttura: 

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

Il returncode è sempre FAILED per gli errori. L'unica eccezione è duplicateWarning, che restituisce SUCCESS ma include una chiave di messaggio di avviso. La tua integrazione dovrebbe controllare sempre il campo messageKey, non solo il codice di ritorno.

Errori di autenticazione e autorizzazione

Questi errori si verificano quando una richiesta non può essere autenticata o quando il chiamante non dispone delle autorizzazioni richieste:

messageKey Messaggio Endpoint che attivano l'errore
checksumError Il checksum non corrisponde. Tutti gli endpoint
invalidPassword La password fornita non è valida. join, end
guestDeniedAccess Accesso negato in base alla guest policy. join
missingToken Manca il session token. getJoinUrl, learningDashboard
missingSession Il session token non è valido. getJoinUrl, learningDashboard
apiNotEnabled Il servizio API non è abilitato su questo server. Tutti gli endpoint

Errori di gestione delle riunioni

Questi errori riguardano la creazione, la partecipazione e la gestione delle riunioni:

messageKey Messaggio Endpoint che attivano l'errore
invalidMeetingId L'meeting ID specificato non esiste. getMeetingInfo, isMeetingRunning, end, join
invalidMeetingIdentifier Una riunione con questo ID non esiste. join
meetingForciblyEnded Impossibile partecipare a una riunione che è stata terminata forzatamente. join
idNotUnique Esiste già una riunione con questo ID. create
nonUniqueVoiceBridge Il voice bridge selezionato è già in uso. create
duplicateWarning Questa conferenza esiste già e potrebbe essere in corso. returncode è SUCCESS create
mismatchCreateTimeParam Il parametro createTime non corrisponde alla riunione corrente. join
maxParticipantsReached È stato raggiunto il numero massimo di partecipanti. join
parentMeetingIDMissing Nessun parentMeetingID specificato per la breakout room. create (breakout)
parentMeetingDoesNotExist Nessuna riunione principale trovata per la breakout room. create (breakout)
meetingNotFound La riunione non è stata trovata. sendChatMessage, getJoinUrl, learningDashboard

Errori di convalida dei parametri

Questi errori vengono restituiti quando mancano parametri obbligatori o quando i dati della richiesta non superano la convalida:

messageKey Messaggio Endpoint che attivano l'errore
MissingParam Il parametro obbligatorio {param} è mancante (dinamico). create, join, end, getMeetingInfo, e altri
missingParamMeetingID L'meeting ID deve essere fornito. create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage
missingParamFullName Il fullName deve essere fornito. join
missingParamRecordID L'recording ID deve essere fornito. updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks
missingParamPublish Il valore publish (true/false) deve essere fornito. publishRecordings
validationError Errore generale di convalida (messaggi vari). Endpoint multipli
unsupportedContentType Il Content-Type della richiesta POST è mancante o non supportato. create, join, end, getMeetingInfo, insertDocument, sendChatMessage
emptyError Il campo non deve essere vuoto. Convalida generale
fileNameError Impossibile decodificare il nome del file. insertDocument

Errori di registrazione

Questi errori sono specifici della gestione delle registrazioni e delle operazioni sulle tracce di testo:

messageKey Messaggio Endpoint che attivano l'errore
notFound Nessuna registrazione trovata. updateRecordings, publishRecordings, deleteRecordings
noRecordings Nessuna registrazione trovata per l'recording ID specificato. putRecordingTextTrack
empty_uploaded_text_track Il file della text track caricato è vuoto. putRecordingTextTrack
paramError Il parametro {paramName} è mancante (dinamico). putRecordingTextTrack
invalidKind Parametro kind non valido — previsto: subtitles o captions. putRecordingTextTrack
invalidLang Parametro language non valido. putRecordingTextTrack

Errori di sessione e utente

Questi errori si verificano durante la convalida della sessione e dell'utente:

messageKey Messaggio Endpoint che attivano l'errore
userNotFound Nessuna sessione attiva trovata per l'user ID specificato. join (con existingUserID)
configNotFound Nessuna configurazione trovata per questo token. Convalida interna
noConfigFound Nessuna configurazione trovata per questa richiesta. Convalida interna

Risoluzione dei problemi

Quando incontri un errore API, segui questi passaggi per diagnosticare e risolvere il problema:

Controlla il messageKey — usa le tabelle dei codici di errore sopra per identificare la causa esatta del fallimento e quale endpoint l'ha provocato.

— l'errore più comune è checsumError. Controlla attentamente di usare il shared secret corretto, il giusto algoritmo di hash e che la query string corrisponda esattamente.

Controlla i parametri obbligatori — gli errori di parametro mancante (MissingParam, missingParamMeetingID, ecc.) indicano che un campo richiesto non è stato incluso nella richiesta.

Conferma lo stato della riunione — errori come invalidMeetingId o meetingForciblyEnded significano che la riunione non esiste o è già terminata. Usa getMeetingInfo per verificare lo stato attuale prima di riprovare.

Controlla i log del server — se il messaggio di errore non è abbastanza specifico, controlla i log del server BigBlueButton in /var/log/bigbluebutton/ per informazioni più dettagliate.

Alcuni messaggi di errore sono dinamici e includono il nome o il valore del parametro problematico. Registra sempre la risposta XML completa dell'API per semplificare il debug.

Quando gestisci il message key duplicateWarning, tieni presente che il returncode è SUCCESS, non FAILED. Questo è un caso speciale in cui BigBlueButton segnala che esiste già una riunione con lo stesso ID, ma restituisce i dati della riunione esistente invece di generare un errore.

Domande frequenti

I codici di errore elencati in questo riferimento sono estratti direttamente dal codice sorgente di BigBlueButton 3.0. La documentazione ufficiale di BBB non include un riferimento completo agli errori. Le definizioni sono distribuite in diversi file sorgente, tra cui ApiErrors.java, ApiController.groovy e RecordingController.groovy.

Sì. Sebbene i valori di messageKey tendano a rimanere stabili tra le versioni, il testo del messaggio leggibile dall'uomo può cambiare. Usa sempre messageKey per la gestione programmatica degli errori, non la stringa del messaggio.

Entrambi indicano che la riunione richiesta non esiste, ma vengono restituiti da endpoint diversi. invalidMeetingId è usato da getMeetingInfo, isMeetingRunning, end e join. meetingNotFound è usato da sendChatMessage, getJoinUrl e learningDashboard.

Il duplicateWarning è un caso speciale: il returncode è SUCCESS, ma il messageKey segnala che esiste già una riunione con lo stesso ID. La tua applicazione dovrebbe verificare se i parametri della riunione esistente corrispondono a quelli previsti. In tal caso, puoi procedere in sicurezza. In caso contrario, scegli un ID riunione diverso.

Le cause più comuni sono: uso del shared secret sbagliato, applicazione dell'algoritmo di hash errato, URL-encoding incoerente della query string oppure inclusione del parametro checksum stesso nell'input dell'hash. Assicurati che la stringa da sottoporre ad hash sia costruita così: apiMethodName + queryString + sharedSecret, dove queryString non include il parametro checksum.

Questo errore viene restituito quando una richiesta POST non include l'header Content-Type o usa un content type che BigBlueButton non supporta. Assicurati che le tue richieste POST includano l'header Content-Type: application/x-www-form-urlencoded.

BigBlueButton può restituire codici di errore aggiuntivi da plugin o moduli personalizzati che non fanno parte dell'API core. I codici elencati qui coprono l'API core BigBlueButton 3.0. Se incontri un messageKey non riconosciuto, controlla i log del server e gli eventuali plugin installati per maggiori informazioni.