Error Model

Allmine API HTTP hataları BaseResponseDto formatının hata varyantıyla döner. Client iş mantığı errors içindeki metinlere değil, HTTP status code'a ve endpoint bağlamına göre karar vermelidir.

Hata response şekli

{
  "isSuccess": false,
  "statusCode": 400,
  "errors": [
    "title should not be empty"
  ],
  "timestamp": "2026-05-21T10:00:00.000Z"
}

data alanı hata response'larında beklenmemelidir. errors her zaman array gibi ele alınmalıdır; tek hata da array içinde gelir.

Lokalizasyon

Request context middleware x-language veya Accept-Language header'ından dili belirler. Client, kullanıcı dili belliyse her request'te açık header göndermelidir.

x-language: tr
Accept-Language: tr-TR,tr;q=0.9,en;q=0.8

Status code anlamları

Auth hatası için önerilen akış

1. Protected request 401 döner.
2. Client refresh token ile POST /api/v1/auth/refresh çağırır.
3. Refresh başarılıysa orijinal request bir kez tekrar edilir.
4. Refresh de 401 dönerse local auth state temizlenir ve login ekranına dönülür.

Aynı anda birden fazla request 401 alırsa refresh çağrısı tekilleştirilmelidir.

let refreshPromise: Promise<void> | null = null;

async function refreshOnce() {
  if (!refreshPromise) {
    refreshPromise = auth.refresh().finally(() => {
      refreshPromise = null;
    });
  }

  return refreshPromise;
}

Validation hataları

Global validation pipe whitelist, forbidNonWhitelisted ve transform ile çalışır. Bu nedenle:

• Tanımlı olmayan body alanları hata üretebilir.
• Query parametreleri DTO tiplerine dönüştürülebilir.
• page, limit, numeric alanlar string gönderilse bile backend'de number'a çevrilebilir; yine de client kendi tipini düzgün göndermelidir.

Socket hataları

WebSocket event'leri HTTP hata wrapper'ını kullanmaz. Örneğin /live-stream-status subscribe hataları şu şekilde gelir:

{
  "code": "TOKEN_INVALID",
  "message": "Geçersiz veya süresi dolmuş token"
}

Socket tarafında da karar code üzerinden verilmelidir.