Kart FiyatKartFiyat API

Genel

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:

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

HTTP Durum Kodları

KodDurumAçıklama
200OKİstek başarılı
400Bad RequestGeçersiz istek parametreleri
401UnauthorizedKimlik doğrulama gerekli veya başarısız
403ForbiddenErişim izni yok (abonelik sorunu)
404Not FoundKaynak bulunamadı
429Too Many RequestsRate limit aşıldı
500Server ErrorSunucu hatası

Hata Kodları Listesi

Kimlik Doğrulama Hataları (401)

Hata KoduAçıklamaÇözüm
MISSING_API_KEYAPI anahtarı gönderilmediAuthorization header'ına Bearer token ekleyin
INVALID_API_KEYGeçersiz veya devre dışı API anahtarıAPI anahtarınızı kontrol edin veya yeni anahtar oluşturun
UNAUTHORIZEDGenel kimlik doğrulama hatasıKimlik bilgilerinizi kontrol edin

Yetkilendirme Hataları (403)

Hata KoduAçıklamaÇözüm
NO_ACTIVE_SUBSCRIPTIONAktif abonelik yokBir API planına abone olun
SUBSCRIPTION_EXPIREDAbonelik süresi dolmuşAboneliğinizi yenileyin
PLAN_UPGRADE_REQUIREDEndpoint mevcut paketinizde kullanılamıyorProfesyonel ya da /plus/*endpoint'leri için Plus paketine geçin

Kaynak Hataları (404)

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

İstek Hataları (400)

Hata KoduAçıklamaÇözüm
QUERY_TOO_SHORTArama sorgusu çok kısaEn 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 KoduDurumAçıklama
PLUS_LISTING_ERROR422İlan bulunamadı, size ait değil veya geçersiz işlem
PLUS_COLLECTION_ERROR422Koleksiyon/kayıt bulunamadı veya size ait değil
PLUS_CSV_ERROR422 / 429Okunamayan CSV, bulunamayan koleksiyon (422) veya günlük 10 işlem limiti (429)

Rate Limit Hataları (429)

Hata KoduAçıklamaÇözüm
DAILY_LIMIT_EXCEEDEDGünlük limit aşıldıErtesi gün tekrar deneyin veya planınızı yükseltin
RATE_LIMIT_EXCEEDEDDakikalı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:

JavaScript
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.