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.

Tek istisna: 401 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.

İ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);

Sık görülen durum kodları

statusCode string bir koddur; endpoint'e göre değişir. Aşağıda sık görülenler alanlara göre gruplanmıştır. (Tam liste API kodunda tanımlıdır.)

Genel

statusCode	Anlamı
`OK`	İşlem başarılı.
`ValidationError`	Gönderilen alanlar eksik/geçersiz.
`Unauthorized`	Yetki yok / oturum geçersiz.
`UserNotFound`	Kullanıcı bulunamadı.
`ProfileIncomplete`	Kullanıcı profili eksik.

Auth

statusCode	Anlamı
`InvalidCredentials`	Kullanıcı adı/şifre hatalı.
`InactiveStudyRoom`	Kullanıcının çalışma odası aktif değil.
`TokenConfigurationMissing`	Sunucu tarafında JWT yapılandırması eksik (sunucu hatası).

Paragraphs

statusCode	Anlamı
`ParagraphNotFound`	Paragraf bulunamadı.
`ParagraphHasNoQuestions`	Paragrafa bağlı soru yok.
`AnswersRequired` / `MissingAnswers`	Tamamlama için cevaplar eksik.
`QuestionMismatch` / `OptionMismatch`	Gönderilen soru/seçenek paragrafla eşleşmiyor.
`InvalidReadingMetrics`	Okuma metrikleri (süre/wpm) geçersiz.

Assignments

statusCode	Anlamı
`AssignmentNotFound`	Ödev bulunamadı.
`AssignmentNotStarted`	Ödev henüz başlamamış.
`AssignmentExpired`	Ödevin süresi geçmiş.
`AssignmentAlreadySubmitted`	Ödev zaten teslim edilmiş.
`AssignmentParagraphNotFound`	Ödeve bağlı paragraf bulunamadı.

GameSessions

statusCode	Anlamı
`GameTemplateNotFound`	Oyun şablonu bulunamadı.
`UnsupportedFramework`	İstenen oyun çerçevesi (framework) desteklenmiyor.
`GameTemplateContentUnavailable`	Şablon içeriği mevcut değil.
`GameTemplateContentInvalid`	Şablon içeriği geçersiz/bozuk.

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