API Hata Başvurusu
Başarısız olan her BigBlueButton API isteği standartlaştırılmış bir XML hata yanıtı döndürür. Bu bölüm, API'nin döndürebileceği tüm hata kodları ve mesajları için BigBlueButton 3.0 kaynak kodu analizine dayanan eksiksiz bir başvuru sunar.
Hata Yanıtı Biçimi
Bir API çağrısı başarısız olduğunda, BigBlueButton üç temel öğe içeren bir XML yanıtı döndürür: bir returncode, makine tarafından okunabilir bir messageKey ve insan tarafından okunabilir bir message. Her hata yanıtı bu yapıyı izler:
<response>
<returncode>FAILED</returncode>
<messageKey>errorKeyHere</messageKey>
<message>A human-readable description of the error.</message>
</response>returncode hata durumlarında her zaman FAILED olur. Tek istisna, SUCCESS döndüren ancak bir uyarı mesajı anahtarı içeren duplicateWarning durumudur. Entegrasyonunuz yalnızca dönüş kodunu değil, her zaman messageKey alanını kontrol etmelidir.
Kimlik Doğrulama ve Yetkilendirme Hataları
Bu hatalar, bir istek kimliği doğrulanamadığında veya çağrıyı yapan taraf gerekli izinlere sahip olmadığında ortaya çıkar:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
checksumError | checksum eşleşmiyor. | Tüm uç noktalar |
invalidPassword | Sağlanan parola geçersiz. | join, end |
guestDeniedAccess | guest policy temelinde erişim reddedildi. | join |
missingToken | session token eksik. | getJoinUrl, learningDashboard |
missingSession | session token geçersiz. | getJoinUrl, learningDashboard |
apiNotEnabled | API hizmeti bu sunucuda etkin değil. | Tüm uç noktalar |
Toplantı Yönetimi Hataları
Bu hatalar toplantı oluşturma, katılma ve yönetme ile ilgilidir:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
invalidMeetingId | Belirtilen meeting ID mevcut değil. | getMeetingInfo, isMeetingRunning, end, join |
invalidMeetingIdentifier | Bu kimliğe sahip bir toplantı mevcut değil. | join |
meetingForciblyEnded | Zorla sonlandırılmış bir toplantıya katılınamaz. | join |
idNotUnique | Bu kimliğe sahip bir toplantı zaten mevcut. | create |
nonUniqueVoiceBridge | Seçilen voice bridge zaten kullanımda. | create |
duplicateWarning | Bu konferans zaten mevcut ve çalışıyor olabilir. returncode değeri SUCCESS | create |
mismatchCreateTimeParam | createTime parametresi mevcut toplantıyla eşleşmiyor. | join |
maxParticipantsReached | Maksimum katılımcı sayısına ulaşıldı. | join |
parentMeetingIDMissing | Breakout room için parentMeetingID belirtilmedi. | create (breakout) |
parentMeetingDoesNotExist | breakout room için üst toplantı bulunamadı. | create (breakout) |
meetingNotFound | Toplantı bulunamadı. | sendChatMessage, getJoinUrl, learningDashboard |
Parametre Doğrulama Hataları
Bu hatalar, gerekli parametreler eksik olduğunda veya istek verisi doğrulamadan geçemediğinde döndürülür:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
MissingParam | Gerekli parametre {param} eksik (dinamik). | create, join, end, getMeetingInfo, ve diğerleri |
missingParamMeetingID | meeting ID sağlanmalıdır. | create, join, isMeetingRunning, end, getMeetingInfo, insertDocument, sendChatMessage |
missingParamFullName | fullName sağlanmalıdır. | join |
missingParamRecordID | recording ID sağlanmalıdır. | updateRecordings, publishRecordings, deleteRecordings, getRecordingTextTracks |
missingParamPublish | publish değeri (true/false) sağlanmalıdır. | publishRecordings |
validationError | Genel doğrulama hatası (çeşitli mesajlar). | Birden fazla uç nokta |
unsupportedContentType | POST isteğinin Content-Type değeri eksik veya desteklenmiyor. | create, join, end, getMeetingInfo, insertDocument, sendChatMessage |
emptyError | Alan boş olmamalıdır. | Genel doğrulama |
fileNameError | Dosya adı çözümlenemedi. | insertDocument |
Kayıt Hataları
Bu hatalar kayıt yönetimi ve metin parçası işlemlerine özeldir:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
notFound | Kayıt bulunamadı. | updateRecordings, publishRecordings, deleteRecordings |
noRecordings | Belirtilen recording ID için kayıt bulunamadı. | putRecordingTextTrack |
empty_uploaded_text_track | Yüklenen text track dosyası boş. | putRecordingTextTrack |
paramError | Parametre {paramName} eksik (dinamik). | putRecordingTextTrack |
invalidKind | Geçersiz kind parametresi — beklenen: subtitles veya captions. | putRecordingTextTrack |
invalidLang | Geçersiz language parametresi. | putRecordingTextTrack |
Oturum ve Kullanıcı Hataları
Bu hatalar oturum ve kullanıcı doğrulaması sırasında oluşur:
messageKey | Mesaj | Tetikleyen Endpoint'ler |
|---|---|---|
userNotFound | Belirtilen user ID için etkin oturum bulunamadı. | join (existingUserID ile) |
configNotFound | Bu belirteç için yapılandırma bulunamadı. | Dahili doğrulama |
noConfigFound | Bu istek için yapılandırma bulunamadı. | Dahili doğrulama |
Sorun Giderme
Bir API hatasıyla karşılaştığınızda, sorunu teşhis etmek ve çözmek için şu adımları izleyin:
messageKey değerini kontrol edin — hatanın tam nedenini ve hangi uç noktanın bunu tetiklediğini belirlemek için yukarıdaki hata kodu tablolarını kullanın.
checsumError'dur. Doğru shared secret, doğru hash algoritmasını kullandığınızı ve sorgu dizesinin tam olarak eşleştiğini tekrar kontrol edin.
Gerekli parametreleri inceleyin — eksik parametre hataları (MissingParam, missingParamMeetingID vb.), gerekli bir alanın isteğe dahil edilmediğini gösterir.
Toplantı durumunu doğrulayın — invalidMeetingId veya meetingForciblyEnded gibi hatalar, toplantının mevcut olmadığını veya zaten sona erdiğini ifade eder. Yeniden denemeden önce mevcut durumu doğrulamak için getMeetingInfo kullanın.
Sunucu günlüklerini inceleyin — hata mesajı yeterince spesifik değilse, daha ayrıntılı bilgi için /var/log/bigbluebutton/ içindeki BigBlueButton sunucu günlüklerini kontrol edin.
Bazı hata mesajları dinamiktir ve sorunlu parametrenin adını veya değerini içerir. Hata ayıklamayı kolaylaştırmak için API’den gelen tam XML yanıtını her zaman günlüğe kaydedin.
duplicateWarning message key işlenirken, returncode değerinin FAILED değil, SUCCESS olduğunu unutmayın. Bu, BigBlueButton'ın aynı kimliğe sahip bir toplantının zaten var olduğunu bildirip hata yükseltmek yerine mevcut toplantı verilerini döndürdüğü özel bir durumdur.
Sıkça Sorulan Sorular
BigBlueButton 3.0 kaynak kodundan çıkarılmıştır. Resmî BBB dokümantasyonu eksiksiz bir hata başvurusu içermez. Tanımlar, ApiErrors.java, ApiController.groovy ve RecordingController.groovy dahil olmak üzere çeşitli kaynak dosyalara dağılmıştır.messageKey değerleri sürümler arasında genellikle kararlı kalsa da, insan tarafından okunabilir mesaj metni değişebilir. Programatik hata işleme için her zaman mesaj dizesini değil, messageKey değerini kullanın.invalidMeetingId; getMeetingInfo, isMeetingRunning, end ve join tarafından kullanılır. meetingNotFound ise sendChatMessage, getJoinUrl ve learningDashboard tarafından kullanılır.duplicateWarning özel bir durumdur: returncode değeri SUCCESS'dur, ancak messageKey aynı kimliğe sahip bir toplantının zaten mevcut olduğunu bildirir. Uygulamanız, mevcut toplantı parametrelerinin amaçladıklarınızla eşleşip eşleşmediğini kontrol etmelidir. Eşleşiyorsa güvenle devam edebilirsiniz. Aksi takdirde farklı bir meeting ID seçin.shared secret kullanmak, yanlış hash algoritması uygulamak, sorgu dizesini tutarsız URL-encode etmek veya checksum parametresinin kendisini hash girdisine dahil etmek. Hashlediğiniz dizenin şu şekilde oluşturulduğundan emin olun: apiMethodName + queryString + sharedSecret; burada queryString, checksum parametresini içermez.POST isteğinde Content-Type başlığı eksik olduğunda veya BigBlueButton'ın desteklemediği bir içerik türü kullanıldığında döndürülür. POST isteklerinizin Content-Type: application/x-www-form-urlencoded başlığını içerdiğinden emin olun.messageKey ile karşılaşırsanız, daha fazla bilgi için sunucu günlüklerini ve kurulu eklentileri kontrol edin.