Hata Kodları

API'den dönebilecek tüm hata kodları ve anlamları.

Hata Formatı

Tüm hata yanıtları aşağıdaki formatta döner:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Kullanıcı dostu hata mesajı"
  }
}

HTTP Durum Kodları

Kod Durum Açıklama
200 OK İstek başarılı
400 Bad Request Geçersiz istek parametreleri
401 Unauthorized Kimlik doğrulama gerekli veya başarısız
403 Forbidden Erişim izni yok (abonelik sorunu)
404 Not Found Kaynak bulunamadı
429 Too Many Requests Rate limit aşıldı
500 Server Error Sunucu hatası

Hata Kodları Listesi

Kimlik Doğrulama Hataları (401)

Hata Kodu Açıklama Çözüm
MISSING_API_KEY API anahtarı gönderilmedi Authorization header'ına Bearer token ekleyin
INVALID_API_KEY Geçersiz veya devre dışı API anahtarı API anahtarınızı kontrol edin veya yeni anahtar oluşturun
UNAUTHORIZED Genel kimlik doğrulama hatası Kimlik bilgilerinizi kontrol edin

Yetkilendirme Hataları (403)

Hata Kodu Açıklama Çözüm
NO_ACTIVE_SUBSCRIPTION Aktif abonelik yok Bir API planına abone olun
SUBSCRIPTION_EXPIRED Abonelik süresi dolmuş Aboneliğinizi yenileyin
PLAN_UPGRADE_REQUIRED Endpoint mevcut paketinizde kullanılamıyor Profesyonel ya da /plus/* endpoint'leri için Plus paketine geçin

Kaynak Hataları (404)

Hata Kodu Açıklama Çözüm
CATEGORY_NOT_FOUND Kategori bulunamadı Kategori ID'sini kontrol edin
ITEM_NOT_FOUND Ürün bulunamadı Ürün ID'sini kontrol edin

İstek Hataları (400)

Hata Kodu Açıklama Çözüm
QUERY_TOO_SHORT Arama sorgusu çok kısa En az 2 karakter uzunluğunda sorgu gönderin

Plus Endpoint Hataları (422 / 429) Plus

/api/v1/plus/* altındaki endpoint'ler hata sebebini error.message alanında Türkçe olarak döner (örn. "Bu ilan size ait değil.").

Hata Kodu Durum Açıklama
PLUS_LISTING_ERROR 422 İlan bulunamadı, size ait değil veya geçersiz işlem
PLUS_COLLECTION_ERROR 422 Koleksiyon/kayıt bulunamadı veya size ait değil
PLUS_CSV_ERROR 422 / 429 Okunamayan CSV, bulunamayan koleksiyon (422) veya günlük 10 işlem limiti (429)

Rate Limit Hataları (429)

Hata Kodu Açıklama Çözüm
DAILY_LIMIT_EXCEEDED Günlük limit aşıldı Ertesi gün tekrar deneyin veya planınızı yükseltin
RATE_LIMIT_EXCEEDED Dakikalık limit aşıldı Retry-After header'ındaki süre kadar bekleyin

Hata Yönetimi

API hatalarını düzgün şekilde yakalamak ve işlemek için örnek kod:

async function apiRequest(endpoint) {
  const response = await fetch(`https://kartfiyat.com/api/v1${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Accept': 'application/json'
    }
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'MISSING_API_KEY':
      case 'INVALID_API_KEY':
        // Kimlik doğrulama hatası - anahtarı kontrol et
        throw new AuthError(data.error.message);

      case 'NO_ACTIVE_SUBSCRIPTION':
      case 'SUBSCRIPTION_EXPIRED':
        // Abonelik hatası - kullanıcıyı yönlendir
        throw new SubscriptionError(data.error.message);

      case 'RATE_LIMIT_EXCEEDED':
        // Rate limit - bekle ve tekrar dene
        const retryAfter = data.error.retry_after || 60;
        await sleep(retryAfter * 1000);
        return apiRequest(endpoint);

      case 'DAILY_LIMIT_EXCEEDED':
        // Günlük limit - bugün daha fazla istek yapılamaz
        throw new DailyLimitError(data.error.message);

      default:
        throw new ApiError(data.error.code, data.error.message);
    }
  }

  return data.data;
}

Önemli

Tüm hataları loglayın ve production ortamında kullanıcılara hata detaylarını gösterirken dikkatli olun. Hassas bilgileri (API anahtarı gibi) asla kullanıcıya göstermeyin.