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>
| Alan | Tip | Açıklama |
isSuccess | bool | İşlem iş kuralları açısından başarılı mı. Önce buna bak. |
statusCode | string | Makine-okur durum kodu. Başarıda "OK", hatada ör. "InvalidCredentials". |
message | string | İnsan-okur açıklama. Loglama/geliştirme için; UI'da doğrudan göstermek zorunda değilsin. |
data | T veya null | Ası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
| statusCode | Anlamı |
OK | İşlem başarılı (tüm başarılı cevaplarda). |
ValidationError | Gönderilen alanlar eksik/geçersiz (ör. ID 0 veya negatif, zorunlu alan boş, değer aralık dışı). Ayrıntı message'dadır. |
Unauthorized | Token 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). |
UserNotFound | Token'daki kullanıcı bulunamadı veya aktif değil. |
IdempotencyConflict | Aynı 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. |
InvalidClientAttemptIdentifier | clientAttemptIdentifier boş (MiniGames, WordLearning) veya boş/128 karakterden uzun (Gamification satın alma, satış, loot box açma). |
Auth
| statusCode | Anlamı |
InvalidCredentials | POST /api/auth/login: kullanıcı adı/e-posta veya şifre hatalı. |
InactiveStudyRoom | login: kullanıcının çalışma odası aktif değil. |
TokenConfigurationMissing | login: sunucuda JWT imzalama anahtarı yapılandırılmamış (sunucu hatası). |
RegistrationConflict | register / register/confirm: e-posta veya kullanıcı adı zaten kayıtlı. |
RegistrationPending | register: bu e-posta/kullanıcı adı için onay bekleyen bir kayıt zaten var. |
RegistrationOtpDeliveryFailed | register: kayıt doğrulama kodu e-postayla gönderilemedi. |
IndividualRegistrationTargetMissing | register / register/confirm: seçilen sınıf için bireysel kayıt çalışma odası bulunamadı (sunucu yapılandırması). |
InvalidOrExpiredRegistrationOtp | register/confirm: kayıt doğrulama kodu hatalı veya süresi dolmuş. |
EmailVerificationDisabled | E-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 / UserNotFound | DELETE /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.
| statusCode | Anlamı |
UnsupportedOs | os değeri ios veya android değil. |
InvalidVersionFormat | version en fazla dört noktayla ayrılmış sayıdan oluşmuyor (ör. 1.4.2 geçerli). |
AppVersionPolicyNotFound | Bu platform için sunucuda sürüm politikası tanımlı değil (sunucu yapılandırması). |
AppVersionPolicyInvalid | Sunucudaki sürüm politikası geçersiz bir sürüm değeri içeriyor (sunucu yapılandırması). |
ValidationError | os veya version boş. |
Me
| statusCode | Anlamı |
ProfileIncomplete | GET /api/me: kullanıcının kurum/alt kurum/çalışma odası bağlantısı eksik. |
Unauthorized / UserNotFound | Token kullanıcısı çözülemedi / bulunamadı. |
Me / Push kayıtları
| statusCode | Anlamı |
InvalidDeviceInstallationIdentifier | Route'taki deviceInstallationId boş olmayan bir GUID değil (ör. FID route'a kondu). |
InvalidPlatform / InvalidPermissionStatus | Tanınmayan platform ya da izin değeri; gövde yoksa InvalidPlatform. |
UnsupportedTargetKind | targetKind Fid değil (RegistrationToken kabul edilmez). |
InvalidTargetValue | FID boş, 256 karakterden uzun ya da boşluk/ASCII dışı karakter içeriyor. |
AppVersionTooLong | appVersion 64 karakteri aşıyor. |
InvalidBindingIdentifier | DELETE: bindingIdentifier yok ya da GUID değil. |
PushRegistrationUnavailable | Sunucuda 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
| statusCode | Anlamı |
ValidationError | paragraphId 0 veya negatif; tamamlamada istek gövdesi yok ya da clientAttemptIdentifier boş/128 karakterden uzun. |
ParagraphNotFound | Paragraf bulunamadı; aktif değil ya da kullanıcının sınıf düzeyi ve diline ait değil. |
ParagraphContentNotFound | Detay: paragraf içerik dosyası depoda bulunamadı. |
ParagraphContentReadFailed | Detay: paragraf içeriği depodan okunamadı (geçici olabilir; tekrar denenebilir). |
ParagraphContentBlobNameMissing | Detay: paragraf kaydında içerik dosya adı yok (içerik hatası). |
ParagraphContentStorageNotConfigured | Detay: içerik deposu sunucuda yapılandırılmamış (sunucu hatası). |
InvalidParagraphContent | Detay: paragraf içerik JSON'u geçersiz. |
IdempotencyConflict | Tamamlama: clientAttemptIdentifier başka bir paragraf için kullanılmış. |
AnswersRequired | Tamamlama: cevap listesi boş veya gönderilmedi. |
MissingAnswers | Tamamlama: paragrafın tüm aktif soruları cevaplanmamış. |
DuplicateQuestionAnswers | Tamamlama: aynı soru için birden fazla cevap gönderildi. |
QuestionMismatch | Tamamlama: cevaplardan biri bu paragrafa ait olmayan bir soruya ait. |
OptionMismatch | Tamamlama: cevaplardan biri, sorusuna ait olmayan bir seçenek gönderiyor. |
ParagraphHasNoQuestions | Tamamlama: paragrafın aktif sorusu yok. |
QuestionHasNoCorrectOption | Tamamlama: sorulardan birinin doğru seçeneği tanımlı değil (içerik hatası). |
InvalidReadingMetrics | Tamamlama: süre pozitif değil veya WPM negatif. Yüksek WPM okumayı reddetmez. |
Assignments
| statusCode | Anlamı |
ValidationError | assignmentId / 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ı. |
AssignmentParagraphAlreadyFinished | Bu ödev paragrafı daha önce bitirilmiş. |
IdempotencyConflict | clientAttemptIdentifier başka bir tamamlama için kullanılmış. |
AnswersRequired | Bitirme: cevap listesi boş veya gönderilmedi. |
MissingAnswers | Bitirme: paragrafın tüm aktif soruları cevaplanmamış. |
DuplicateQuestionAnswers | Bitirme: aynı soru için birden fazla cevap gönderildi. |
QuestionMismatch | Bitirme: cevaplardan biri bu paragrafa ait olmayan bir soruya ait. |
OptionMismatch | Bitirme: cevaplardan biri, sorusuna ait olmayan bir seçenek gönderiyor. |
ParagraphHasNoQuestions | Bitirme: paragrafın aktif sorusu yok. |
QuestionHasNoCorrectOption | Bitirme: sorulardan birinin doğru seçeneği tanımlı değil (içerik hatası). |
InvalidReadingMetrics | Bitirme: süre pozitif değil veya WPM negatif. Yüksek WPM okumayı reddetmez. |
GameSessions
| statusCode | Anlamı |
ProgressStateMissing | GET /api/game-sessions/daily: kullanıcının gelişim alanı durumları yok (hesap kurulumu eksik). |
SelectionConfigMissing | daily: kullanıcı için geçerli öge seçim yapılandırması bulunamadı (sunucu yapılandırması). |
SelectionConfigFrameworkRuleMissing | daily: seçim yapılandırmasında kullanıcının sınıfına uygun framework kuralı yok (sunucu yapılandırması). |
GameSessionTemplateMissing | daily: 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. |
ValidationError | Bitirme: 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. |
GameSessionItemAlreadyFinished | Bitirme: öge daha önce (başka bir denemeyle) bitirilmiş. |
GameSessionNotActive | Bitirme: ögenin oturumu artık Active değil. |
IdempotencyConflict | Bitirme: clientAttemptIdentifier başka bir öge için kullanılmış. |
Gamification
| statusCode | Anlamı |
ClassroomNotFound | Sı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. |
SubCorporationNotFound | Alt kurum sıralaması: kullanıcının alt kurumu bulunamadı. |
InvalidLeaderboardPeriod | Sı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ı). |
ItemNotFound | Satın alma: itemCode boş veya katalogda yok. |
ItemNotPurchasable | Satın alma: item satışta değil veya fiyatı tanımlı değil. |
ItemAlreadyOwned | Satın alma: stack'lenemeyen item'a zaten sahip olunuyor. |
InsufficientCredits | Satın alma: Credits bakiyesi yetersiz. |
PurchaseReplayNotFound | Satın alma tekrarı: önceki satın almanın sonucu bulunamadı (veri tutarsızlığı). |
UserItemNotFound | Tak / çıkar / sat: kullanıcı item'ı bulunamadı veya tüketilmiş. |
ItemNotEquippable | Tak: item avatarda takılamaz. |
ItemExpired | Tak: kullanıcı item'ının süresi dolmuş. |
InvalidQuantity | Sat: quantity 1-1000 aralığında değil. |
ItemNotSellable | Sat: item satılamaz, pasif veya satış fiyatı tanımlı değil. |
ItemEquipped | Sat: item şu an avatarda takılı; önce çıkarılmalı. |
InsufficientItemQuantity | Sat: satılmak istenen adet sahip olunandan fazla. |
SellReplayNotFound | Satış tekrarı: önceki satışın sonucu bulunamadı (veri tutarsızlığı). |
UserLootBoxNotFound | Loot box açma: kutu bulunamadı veya kullanıcıya ait değil. |
LootBoxAlreadyOpened | Loot box açma: kutu daha önce (başka bir denemeyle) açılmış. |
LootBoxExpired | Loot box açma: kutunun süresi dolmuş. |
LootBoxRevoked | Loot box açma: kutu geri alınmış. |
LootBoxInactive | Loot box açma: kutunun katalog kaydı pasif. |
LootBoxHasNoActiveRewardRules | Loot box açma: kutuda verilebilecek aktif ödül kuralı yok (katalog hatası). |
OpeningReplayNotFound | Loot box açma tekrarı: önceki açılışın sonucu bulunamadı (veri tutarsızlığı). |
UserAchievementNotFound | Achievement "görüldü": kayıt bulunamadı veya kullanıcıya ait değil. |
IdempotencyConflict | Satın alma / satış / loot box açma: clientAttemptIdentifier başka bir işlem için kullanılmış. |
MiniGames
| statusCode | Anlamı |
MiniGamesDisabled | Mini oyunlar sunucuda kapalı. |
InvalidMiniGame | miniGameCode boş. |
MiniGameNotAvailable | Mini oyun katalogda yok, pasif veya kullanıcının sınıfı için açık değil. |
DailySessionRequired | Mini oyun oynanmadan önce günün GameSession'ı tamamlanmalı. |
InvalidMiniGameLevel | attemptedLevel oyunun seviye aralığı dışında. |
MiniGameLevelMismatch | attemptedLevel kullanıcının bu oyundaki güncel seviyesiyle aynı değil. |
InvalidMiniGameScore | score 0-100 aralığında değil. |
InvalidMiniGameDuration | durationSeconds negatif. |
InvalidClientAttemptIdentifier | clientAttemptIdentifier boş. |
IdempotencyConflict | clientAttemptIdentifier başka bir mini oyun denemesi için kullanılmış. |
Events
| statusCode | Anlamı |
EventNotFound | Etkinlik yok, yayında değil, oyuncu hedef kitlede değil, özellik kapalı ya da eventIdentifier geçersiz. |
EventNotActive | Koşu başlatma: etkinlik henüz başlamadı ya da bitti. |
EventNotPlayable | Koşu başlatma: etkinliğin soru içeriği eksik. |
NoAttemptsLeft | Koşu başlatma: oyuncunun bu etkinlikte sayılan koşusu var (bitmiş ya da yarım). |
RunNotFound | Koşu bu oyuncuya ait değil, runIdentifier geçersiz ya da koşunun yerine yenisi açıldı. |
RunFinished | next / cevap: koşu bitti (sunucu kendisi bitirmiş olabilir); istemci finish çağırır. |
QuestionNotServed | Cevap: soru bu koşuda servis edilmedi ya da questionIdentifier geçersiz. |
InvalidOption | Cevap: seçenek bu soruya ait değil ya da optionIdentifier geçersiz. |
NoMoreQuestions | next: son soru cevaplandı. |
WordLearning
| statusCode | Anlamı |
WordLearningDisabled | WordLearning sunucuda kapalı. |
WordLearningStateNotFound | Kullanıcının WordLearning durumu bulunamadı. |
WordLearningContentUnavailable | Oturum başlatma: kullanıcı için uygun kelime içeriği yok. |
InvalidWordLearningSession | Bitirme: oturum ID'si boş. |
WordLearningSessionNotFound | Bitirme: aktif oturum bulunamadı. |
WordLearningSessionExpired | Bitirme: oturumun süresi dolmuş (oturum Expired olur). |
WordLearningSessionAlreadyFinished | Bitirme: oturum zaten bitirilmiş. |
InvalidWordLearningResults | Bitirme: 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. |
InvalidClientAttemptIdentifier | Bitirme: clientAttemptIdentifier boş. |
IdempotencyConflict | Bitirme: clientAttemptIdentifier başka bir oturum için kullanılmış. |
TestOps (yalnız test ortamı)
| statusCode | Anlamı |
TestOpsDisabled | TestOps endpoint'leri bu ortamda kapalı. |
TestOpsUnauthorized | X-TestOps-Key başlığı eksik veya hatalı. |
UserNotFound | userIdentifier ile kullanıcı bulunamadı. |
InvalidWalletAdjustment | Wallet değişimi 0 veya MaxWalletAdjustmentAbs sınırı dışında. |
InsufficientWalletBalance | Wallet değişimi bakiyeyi negatife düşürüyor. |
InvalidXpAdjustment | XP değişimi 0 veya MaxXpAdjustmentAbs sınırı dışında. |
PlayerLevelTypeNotFound | playerLevelTypeCode katalogda yok. |
PlayerLevelStateNotFound | Kullanıcının bu level tipi için seviye durumu yok. |
LootBoxNotFound | lootBoxCode katalogda yok. |
InvalidLootBoxQuantity | Sandık adedi 1 ile MaxLootBoxQuantity arasında değil. |
DailySessionNotFound | Günlük oturum sıfırlama: bugünün oturumu yok. |
InvalidDailySessionSelection | Oturum zorlama: frameworkCodes ve templateCodes ikisi de boş. |
GameTemplatesNotFound | Oturum zorlama: kullanıcının sınıfına uyan aktif şablon yok. |
DailySessionAlreadyExists | Oturum zorlama: bugünün oturumu var ve replaceTodaySession=false. |
MiniGameNotFound | Mini oyun sıfırlama/seviye: miniGameCode katalogda yok. |
InvalidFeedText | Feed oluşturma/güncelleme: displayText boş. |
InvalidFeedPayload | Feed oluşturma/güncelleme: payloadJson geçerli JSON değil. |
FeedItemNotFound | Feed güncelleme/silme: feed öğesi bulunamadı. |
EventNotFound | Etkinlik sıfırlama/aralık: eventIdentifier ile etkinlik bulunamadı. |
EventNotTestOnly | Etkinlik sıfırlama/aralık: etkinliğin hedef kitlesi yalnız test alt kurumlarından oluşmuyor. |
InvalidEventWindow | Etkinlik aralığı: endsOnUtc, startsOnUtc'tan sonra değil. |
InvalidPushTestContent | Test bildirimi: title (en fazla 65) veya body (en fazla 180) boş ya da sınırı aşıyor. |
PushEnvironmentNotConfigured | Test bildirimi: sunucuda Push:Environment ayarlı değil. |
PushTestUserNotAllowed | Test bildirimi: öğrenci TestOps:PushUserIdentifiers listesinde değil. |
NoDeliverableInstallation | Test bildirimi: öğrencinin aktif, izinli ve son 30 günde görülmüş cihaz kaydı yok. |
Feedback
| statusCode | Anlamı |
TopicRequired | Konu (topicCode/customTopic) gönderilmedi. |
InvalidRating | Puan 1-5 değil (0 = puan yok). |
MessageTooLong / FieldTooLong | Metin alanı sınırı aşıyor; kırpılmaz, reddedilir. |
InvalidMetadata | metadata JSON nesnesi değil ya da 8192 bayt üstü. |
TooManyAttachments / AttachmentTooLarge / EmptyAttachment / UnsupportedAttachmentType | Dosya sayısı, boyutu ya da türü geçersiz. |
UnsupportedContentType | Gövde form değil (ör. JSON). |
FeedbackRateLimited | 10 dakikada 5'ten fazla gönderim. |
FeedbackTopicsNotConfigured | topicCode eşleşmedi (veya gönderilmedi) ve sunucuda yedek olarak kullanılacak aktif serbest (isCustom) konu yok (sunucu yapılandırması). |
AttachmentStorageFailed | Dosya depolanamadı; aynı clientFeedbackIdentifier ile tekrar denenebilir. |
Ayrıntı: Geri Bildirim.