Temel Kavramlar

Cevaplar & Hatalar

API'deki her cevap aynı zarfla gelir: ApiResponse<T>. Başarı da hata da bu zarfın içindedir. Bu yüzden istemcide önce isSuccess/statusCode kontrol edilir.

Zarf: ApiResponse<T>

AlanTipAçıklama
isSuccessboolİşlem iş kuralları açısından başarılı mı. Önce buna bak.
statusCodestringMakine-okur durum kodu. Başarıda "OK", hatada ör. "InvalidCredentials".
messagestringİnsan-okur açıklama. Loglama/geliştirme için; UI'da doğrudan göstermek zorunda değilsin.
dataT veya nullAsıl veri. Başarıda dolu, hatada genelde null.

Başarılı cevap

{
  "isSuccess": true,
  "statusCode": "OK",
  "message": "OK",
  "data": { "...": "endpoint'e özel gövde" }
}

Hatalı cevap

{
  "isSuccess": false,
  "statusCode": "InvalidCredentials",
  "message": "User credentials are invalid.",
  "data": null
}
Önemli: iş hataları da HTTP 200 döner Endpoint'ler iş kuralı hatalarında dahi HTTP 200 ile cevap verir; gerçek sonuç gövdedeki isSuccess ve statusCode'dadır. HTTP durum koduna güvenip başarı varsayma — önce isSuccess'e bak.
İstisnalar: 401 ve çok büyük istek Korumalı endpoint'e geçersiz/eksik token ile gidilirse API HTTP 401 döner ve bu cevap ApiResponse zarfında gelmez. Bkz. Kimlik Doğrulama. Benzer şekilde dosya yüklemede istek gövdesi üst sınırı (geri bildirimde 28 MB) aşılırsa envelope dışında HTTP 400 döner; bkz. Geri Bildirim.
Tarih alanları: ...Utc her zaman UTC'dir Adı Utc ile biten alanlar UTC'dir, ancak değer çoğu yanıtta saat dilimi eki olmadan gelir (ör. "2026-10-23T21:00:00"; bazılarında Z bulunur). Ek yoksa değeri yerel saat olarak değil, UTC olarak çözümle. sessionDate, studentDay gibi gün alanları İstanbul günüdür, saat bilgisi taşımaz.

İstemci tarafında doğru kullanım

Sözde-kod
var res = Deserialize<ApiResponse<T>>(json);
if (!res.isSuccess) {
    // res.statusCode'a göre işle: "InvalidCredentials", "AssignmentExpired", ...
    HandleError(res.statusCode, res.message);
    return;
}
Use(res.data);

Durum kodları (statusCode)

statusCode string bir koddur; endpoint'e göre değişir. Başarılı her cevapta değer "OK"'dir (ör. RegistrationOtpSent, PasswordResetAccepted gibi bilgiler yalnız message alanında gelir). Aşağıda public API'nin döndürebildiği tüm hata kodları alana göre gruplanmıştır. İstemci kararlarını message metnine değil statusCode'a göre vermelidir.

Genel

statusCodeAnlamı
OKİşlem başarılı (tüm başarılı cevaplarda).
ValidationErrorGönderilen alanlar eksik/geçersiz (ör. ID 0 veya negatif, zorunlu alan boş, değer aralık dışı). Ayrıntı message'dadır.
UnauthorizedToken geçerli ama içinden kullanıcı çözülemedi. Token hiç yoksa/geçersizse HTTP 401 envelope'sız döner (yukarıya bakın).
UserNotFoundToken'daki kullanıcı bulunamadı veya aktif değil.
IdempotencyConflictAynı clientAttemptIdentifier daha önce başka bir kayıt/işlem için kullanılmış. Aynı işlem için tekrar gönderim hata değildir; isIdempotentReplay: true döner.
InvalidClientAttemptIdentifierclientAttemptIdentifier boş (MiniGames, WordLearning) veya boş/128 karakterden uzun (Gamification satın alma, satış, loot box açma).

Auth

statusCodeAnlamı
InvalidCredentialsPOST /api/auth/login: kullanıcı adı/e-posta veya şifre hatalı.
InactiveStudyRoomlogin: kullanıcının çalışma odası aktif değil.
TokenConfigurationMissinglogin: sunucuda JWT imzalama anahtarı yapılandırılmamış (sunucu hatası).
RegistrationConflictregister / register/confirm: e-posta veya kullanıcı adı zaten kayıtlı.
RegistrationPendingregister: bu e-posta/kullanıcı adı için onay bekleyen bir kayıt zaten var.
RegistrationOtpDeliveryFailedregister: kayıt doğrulama kodu e-postayla gönderilemedi.
IndividualRegistrationTargetMissingregister / register/confirm: seçilen sınıf için bireysel kayıt çalışma odası bulunamadı (sunucu yapılandırması).
InvalidOrExpiredRegistrationOtpregister/confirm: kayıt doğrulama kodu hatalı veya süresi dolmuş.
EmailVerificationDisabledE-posta doğrulama sunucuda kapalı (register/confirm, e-posta doğrulama isteği/onayı).
InvalidOrExpiredTokenŞifre sıfırlama onayı veya e-posta doğrulama onayı: kod/token hatalı veya süresi dolmuş.
Unauthorized / UserNotFoundDELETE /api/auth/account: token kullanıcısı çözülemedi / bulunamadı.

AppVersion (sürüm kontrolü)

Sürümün desteklenip desteklenmediği hata kodu değildir; başarılı cevapta data.status (Supported, UpdateRequired, UnsupportedVersion) ile gelir.

statusCodeAnlamı
UnsupportedOsos değeri ios veya android değil.
InvalidVersionFormatversion en fazla dört noktayla ayrılmış sayıdan oluşmuyor (ör. 1.4.2 geçerli).
AppVersionPolicyNotFoundBu platform için sunucuda sürüm politikası tanımlı değil (sunucu yapılandırması).
AppVersionPolicyInvalidSunucudaki sürüm politikası geçersiz bir sürüm değeri içeriyor (sunucu yapılandırması).
ValidationErroros veya version boş.

Me

statusCodeAnlamı
ProfileIncompleteGET /api/me: kullanıcının kurum/alt kurum/çalışma odası bağlantısı eksik.
Unauthorized / UserNotFoundToken kullanıcısı çözülemedi / bulunamadı.

Me / Push kayıtları

statusCodeAnlamı
InvalidDeviceInstallationIdentifierRoute'taki deviceInstallationId boş olmayan bir GUID değil (ör. FID route'a kondu).
InvalidPlatform / InvalidPermissionStatusTanınmayan platform ya da izin değeri; gövde yoksa InvalidPlatform.
UnsupportedTargetKindtargetKind Fid değil (RegistrationToken kabul edilmez).
InvalidTargetValueFID boş, 256 karakterden uzun ya da boşluk/ASCII dışı karakter içeriyor.
AppVersionTooLongappVersion 64 karakteri aşıyor.
InvalidBindingIdentifierDELETE: bindingIdentifier yok ya da GUID değil.
PushRegistrationUnavailableSunucuda push kaydı yapılandırılmamış.

Ayrıntı: Push Bildirimleri.

Okuma hızı alanları

CurrentWpm, AverageWpm, AssignmentAverageWpm ve completion özetindeki Wpm alanlarında 0, uygun hız ölçümü yok anlamındadır. Ekranda “—” gösterin; grafik noktası veya ortalama örneği eklemeyin. Ham WPM veya kelime/süre oranı 1000 WPM üzerindeyse hız ölçümü dışlanır; okuma, cevaplar, anlama ve tamamlama geçerli kalır. 1000 dahildir.

Paragraphs

statusCodeAnlamı
ValidationErrorparagraphId 0 veya negatif; tamamlamada istek gövdesi yok ya da clientAttemptIdentifier boş/128 karakterden uzun.
ParagraphNotFoundParagraf bulunamadı; aktif değil ya da kullanıcının sınıf düzeyi ve diline ait değil.
ParagraphContentNotFoundDetay: paragraf içerik dosyası depoda bulunamadı.
ParagraphContentReadFailedDetay: paragraf içeriği depodan okunamadı (geçici olabilir; tekrar denenebilir).
ParagraphContentBlobNameMissingDetay: paragraf kaydında içerik dosya adı yok (içerik hatası).
ParagraphContentStorageNotConfiguredDetay: içerik deposu sunucuda yapılandırılmamış (sunucu hatası).
InvalidParagraphContentDetay: paragraf içerik JSON'u geçersiz.
IdempotencyConflictTamamlama: clientAttemptIdentifier başka bir paragraf için kullanılmış.
AnswersRequiredTamamlama: cevap listesi boş veya gönderilmedi.
MissingAnswersTamamlama: paragrafın tüm aktif soruları cevaplanmamış.
DuplicateQuestionAnswersTamamlama: aynı soru için birden fazla cevap gönderildi.
QuestionMismatchTamamlama: cevaplardan biri bu paragrafa ait olmayan bir soruya ait.
OptionMismatchTamamlama: cevaplardan biri, sorusuna ait olmayan bir seçenek gönderiyor.
ParagraphHasNoQuestionsTamamlama: paragrafın aktif sorusu yok.
QuestionHasNoCorrectOptionTamamlama: sorulardan birinin doğru seçeneği tanımlı değil (içerik hatası).
InvalidReadingMetricsTamamlama: süre pozitif değil veya WPM negatif. Yüksek WPM okumayı reddetmez.

Assignments

statusCodeAnlamı
ValidationErrorassignmentId / userAssignmentParagraphId 0 veya negatif; bitirmede istek gövdesi yok ya da clientAttemptIdentifier boş/128 karakterden uzun.
AssignmentNotFoundÖdev bulunamadı veya kullanıcıya atanmamış.
AssignmentNotStartedÖdevin başlangıç zamanı gelmemiş.
AssignmentExpiredÖdevin teslim tarihi geçmiş.
AssignmentAlreadySubmittedÖdev zaten teslim edilmiş.
AssignmentParagraphNotFoundÖdeve bağlı kullanıcı paragraf kaydı bulunamadı.
AssignmentParagraphAlreadyFinishedBu ödev paragrafı daha önce bitirilmiş.
IdempotencyConflictclientAttemptIdentifier başka bir tamamlama için kullanılmış.
AnswersRequiredBitirme: cevap listesi boş veya gönderilmedi.
MissingAnswersBitirme: paragrafın tüm aktif soruları cevaplanmamış.
DuplicateQuestionAnswersBitirme: aynı soru için birden fazla cevap gönderildi.
QuestionMismatchBitirme: cevaplardan biri bu paragrafa ait olmayan bir soruya ait.
OptionMismatchBitirme: cevaplardan biri, sorusuna ait olmayan bir seçenek gönderiyor.
ParagraphHasNoQuestionsBitirme: paragrafın aktif sorusu yok.
QuestionHasNoCorrectOptionBitirme: sorulardan birinin doğru seçeneği tanımlı değil (içerik hatası).
InvalidReadingMetricsBitirme: süre pozitif değil veya WPM negatif. Yüksek WPM okumayı reddetmez.

GameSessions

statusCodeAnlamı
ProgressStateMissingGET /api/game-sessions/daily: kullanıcının gelişim alanı durumları yok (hesap kurulumu eksik).
SelectionConfigMissingdaily: kullanıcı için geçerli öge seçim yapılandırması bulunamadı (sunucu yapılandırması).
SelectionConfigFrameworkRuleMissingdaily: seçim yapılandırmasında kullanıcının sınıfına uygun framework kuralı yok (sunucu yapılandırması).
GameSessionTemplateMissingdaily: bugünkü oturum için uygun oyun şablonu bulunamadı.
GameSessionItemNotFoundÖge detayı / bitirme: öge bulunamadı veya kullanıcıya ait değil.
GameTemplateContentNotFoundÖge detayı: şablon içerik dosyası depoda bulunamadı.
GameTemplateContentReadFailedÖge detayı: şablon içeriği depodan okunamadı (geçici olabilir; tekrar denenebilir).
GameTemplateContentBlobNameMissingÖge detayı: ögede içerik dosya adı yok (içerik hatası).
GameTemplateContentStorageNotConfiguredÖge detayı: içerik deposu sunucuda yapılandırılmamış (sunucu hatası).
InvalidGameTemplateContentÖge detayı: şablon içerik JSON'u geçersiz veya Unity formatına çevrilemedi.
ValidationErrorBitirme: ID 0 veya negatif; gövde ya da clientAttemptIdentifier eksik/128 karakterden uzun; score 0-100 dışında; cevap sayıları negatif veya toplamı 0; durationSeconds 0 veya negatif.
GameSessionItemAlreadyFinishedBitirme: öge daha önce (başka bir denemeyle) bitirilmiş.
GameSessionNotActiveBitirme: ögenin oturumu artık Active değil.
IdempotencyConflictBitirme: clientAttemptIdentifier başka bir öge için kullanılmış.

Gamification

statusCodeAnlamı
ClassroomNotFoundSınıf görünümü, sınıf feed'i, sınıf sıralaması: kullanıcının çalışma odası yok veya aktif değil.
SubCorporationNotFoundAlt kurum sıralaması: kullanıcının alt kurumu bulunamadı.
InvalidLeaderboardPeriodSıralama: period AllTime/Weekly/Monthly değil ya da year/week/month geçersiz.
RewardGrantNotFoundÖdül claim: ödül bulunamadı veya kullanıcıya ait değil.
InvalidRewardGrantStatusÖdül claim: ödül Pending durumda değil.
RewardGrantExpiredÖdül claim: ödülün son geçerlilik zamanı geçmiş.
RewardGrantRevokedÖdül claim: ödül geri alınmış.
InvalidRewardKindÖdül claim: ödül türü tanınmıyor (veri hatası).
RewardItemNotAvailableÖdül claim / loot box açma: ödül item'ı katalogda yok veya pasif.
LootBoxNotAvailableÖdül claim: ödüldeki loot box katalogda yok veya pasif.
MaxStackReachedÖdül claim / satın alma: item stack'lenemez ve zaten sahip olunuyor, ya da azami stack aşılıyor.
RewardClaimReplayNotFoundÖdül claim tekrarı: önceki claim'in sonucu (wallet hareketi/envanter kaydı) bulunamadı (veri tutarsızlığı).
RewardGrantRepositoryNotConfiguredÖdül sistemi sunucuda yapılandırılmamış (sunucu hatası).
ItemNotFoundSatın alma: itemCode boş veya katalogda yok.
ItemNotPurchasableSatın alma: item satışta değil veya fiyatı tanımlı değil.
ItemAlreadyOwnedSatın alma: stack'lenemeyen item'a zaten sahip olunuyor.
InsufficientCreditsSatın alma: Credits bakiyesi yetersiz.
PurchaseReplayNotFoundSatın alma tekrarı: önceki satın almanın sonucu bulunamadı (veri tutarsızlığı).
UserItemNotFoundTak / çıkar / sat: kullanıcı item'ı bulunamadı veya tüketilmiş.
ItemNotEquippableTak: item avatarda takılamaz.
ItemExpiredTak: kullanıcı item'ının süresi dolmuş.
InvalidQuantitySat: quantity 1-1000 aralığında değil.
ItemNotSellableSat: item satılamaz, pasif veya satış fiyatı tanımlı değil.
ItemEquippedSat: item şu an avatarda takılı; önce çıkarılmalı.
InsufficientItemQuantitySat: satılmak istenen adet sahip olunandan fazla.
SellReplayNotFoundSatış tekrarı: önceki satışın sonucu bulunamadı (veri tutarsızlığı).
UserLootBoxNotFoundLoot box açma: kutu bulunamadı veya kullanıcıya ait değil.
LootBoxAlreadyOpenedLoot box açma: kutu daha önce (başka bir denemeyle) açılmış.
LootBoxExpiredLoot box açma: kutunun süresi dolmuş.
LootBoxRevokedLoot box açma: kutu geri alınmış.
LootBoxInactiveLoot box açma: kutunun katalog kaydı pasif.
LootBoxHasNoActiveRewardRulesLoot box açma: kutuda verilebilecek aktif ödül kuralı yok (katalog hatası).
OpeningReplayNotFoundLoot box açma tekrarı: önceki açılışın sonucu bulunamadı (veri tutarsızlığı).
UserAchievementNotFoundAchievement "görüldü": kayıt bulunamadı veya kullanıcıya ait değil.
IdempotencyConflictSatın alma / satış / loot box açma: clientAttemptIdentifier başka bir işlem için kullanılmış.

MiniGames

statusCodeAnlamı
MiniGamesDisabledMini oyunlar sunucuda kapalı.
InvalidMiniGameminiGameCode boş.
MiniGameNotAvailableMini oyun katalogda yok, pasif veya kullanıcının sınıfı için açık değil.
DailySessionRequiredMini oyun oynanmadan önce günün GameSession'ı tamamlanmalı.
InvalidMiniGameLevelattemptedLevel oyunun seviye aralığı dışında.
MiniGameLevelMismatchattemptedLevel kullanıcının bu oyundaki güncel seviyesiyle aynı değil.
InvalidMiniGameScorescore 0-100 aralığında değil.
InvalidMiniGameDurationdurationSeconds negatif.
InvalidClientAttemptIdentifierclientAttemptIdentifier boş.
IdempotencyConflictclientAttemptIdentifier başka bir mini oyun denemesi için kullanılmış.

Events

statusCodeAnlamı
EventNotFoundEtkinlik yok, yayında değil, oyuncu hedef kitlede değil, özellik kapalı ya da eventIdentifier geçersiz.
EventNotActiveKoşu başlatma: etkinlik henüz başlamadı ya da bitti.
EventNotPlayableKoşu başlatma: etkinliğin soru içeriği eksik.
NoAttemptsLeftKoşu başlatma: oyuncunun bu etkinlikte sayılan koşusu var (bitmiş ya da yarım).
RunNotFoundKoşu bu oyuncuya ait değil, runIdentifier geçersiz ya da koşunun yerine yenisi açıldı.
RunFinishednext / cevap: koşu bitti (sunucu kendisi bitirmiş olabilir); istemci finish çağırır.
QuestionNotServedCevap: soru bu koşuda servis edilmedi ya da questionIdentifier geçersiz.
InvalidOptionCevap: seçenek bu soruya ait değil ya da optionIdentifier geçersiz.
NoMoreQuestionsnext: son soru cevaplandı.

WordLearning

statusCodeAnlamı
WordLearningDisabledWordLearning sunucuda kapalı.
WordLearningStateNotFoundKullanıcının WordLearning durumu bulunamadı.
WordLearningContentUnavailableOturum başlatma: kullanıcı için uygun kelime içeriği yok.
InvalidWordLearningSessionBitirme: oturum ID'si boş.
WordLearningSessionNotFoundBitirme: aktif oturum bulunamadı.
WordLearningSessionExpiredBitirme: oturumun süresi dolmuş (oturum Expired olur).
WordLearningSessionAlreadyFinishedBitirme: oturum zaten bitirilmiş.
InvalidWordLearningResultsBitirme: sonuç listesi boş; oturumdaki her öge tam bir kez gönderilmemiş; NewCard ögesi seçenek gönderiyor; Quiz ögesi seçenek göndermiyor ya da seçenek soruya ait değil.
InvalidClientAttemptIdentifierBitirme: clientAttemptIdentifier boş.
IdempotencyConflictBitirme: clientAttemptIdentifier başka bir oturum için kullanılmış.

TestOps (yalnız test ortamı)

statusCodeAnlamı
TestOpsDisabledTestOps endpoint'leri bu ortamda kapalı.
TestOpsUnauthorizedX-TestOps-Key başlığı eksik veya hatalı.
UserNotFounduserIdentifier ile kullanıcı bulunamadı.
InvalidWalletAdjustmentWallet değişimi 0 veya MaxWalletAdjustmentAbs sınırı dışında.
InsufficientWalletBalanceWallet değişimi bakiyeyi negatife düşürüyor.
InvalidXpAdjustmentXP değişimi 0 veya MaxXpAdjustmentAbs sınırı dışında.
PlayerLevelTypeNotFoundplayerLevelTypeCode katalogda yok.
PlayerLevelStateNotFoundKullanıcının bu level tipi için seviye durumu yok.
LootBoxNotFoundlootBoxCode katalogda yok.
InvalidLootBoxQuantitySandık adedi 1 ile MaxLootBoxQuantity arasında değil.
DailySessionNotFoundGünlük oturum sıfırlama: bugünün oturumu yok.
InvalidDailySessionSelectionOturum zorlama: frameworkCodes ve templateCodes ikisi de boş.
GameTemplatesNotFoundOturum zorlama: kullanıcının sınıfına uyan aktif şablon yok.
DailySessionAlreadyExistsOturum zorlama: bugünün oturumu var ve replaceTodaySession=false.
MiniGameNotFoundMini oyun sıfırlama/seviye: miniGameCode katalogda yok.
InvalidFeedTextFeed oluşturma/güncelleme: displayText boş.
InvalidFeedPayloadFeed oluşturma/güncelleme: payloadJson geçerli JSON değil.
FeedItemNotFoundFeed güncelleme/silme: feed öğesi bulunamadı.
EventNotFoundEtkinlik sıfırlama/aralık: eventIdentifier ile etkinlik bulunamadı.
EventNotTestOnlyEtkinlik sıfırlama/aralık: etkinliğin hedef kitlesi yalnız test alt kurumlarından oluşmuyor.
InvalidEventWindowEtkinlik aralığı: endsOnUtc, startsOnUtc'tan sonra değil.
InvalidPushTestContentTest bildirimi: title (en fazla 65) veya body (en fazla 180) boş ya da sınırı aşıyor.
PushEnvironmentNotConfiguredTest bildirimi: sunucuda Push:Environment ayarlı değil.
PushTestUserNotAllowedTest bildirimi: öğrenci TestOps:PushUserIdentifiers listesinde değil.
NoDeliverableInstallationTest bildirimi: öğrencinin aktif, izinli ve son 30 günde görülmüş cihaz kaydı yok.

Feedback

statusCodeAnlamı
TopicRequiredKonu (topicCode/customTopic) gönderilmedi.
InvalidRatingPuan 1-5 değil (0 = puan yok).
MessageTooLong / FieldTooLongMetin alanı sınırı aşıyor; kırpılmaz, reddedilir.
InvalidMetadatametadata JSON nesnesi değil ya da 8192 bayt üstü.
TooManyAttachments / AttachmentTooLarge / EmptyAttachment / UnsupportedAttachmentTypeDosya sayısı, boyutu ya da türü geçersiz.
UnsupportedContentTypeGövde form değil (ör. JSON).
FeedbackRateLimited10 dakikada 5'ten fazla gönderim.
FeedbackTopicsNotConfiguredtopicCode eşleşmedi (veya gönderilmedi) ve sunucuda yedek olarak kullanılacak aktif serbest (isCustom) konu yok (sunucu yapılandırması).
AttachmentStorageFailedDosya depolanamadı; aynı clientFeedbackIdentifier ile tekrar denenebilir.

Ayrıntı: Geri Bildirim.

Alan bazlı tam şema Her endpoint'in data gövdesindeki alanların tam listesi İnteraktif API Referansı'nda yer alır.