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ı
| 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:
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.