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 functionapiRequest(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 etthrow new AuthError(data.error.message);
case'NO_ACTIVE_SUBSCRIPTION':
case'SUBSCRIPTION_EXPIRED':
// Abonelik hatası - kullanıcıyı yönlendirthrow new SubscriptionError(data.error.message);
case'RATE_LIMIT_EXCEEDED':
// Rate limit - bekle ve tekrar deneconst 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ılamazthrow 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.