​
Hata Kodları ve Çözümleri

API isteklerinizde aşağıdaki hata kodlarıyla karşılaşabilirsiniz. Hata mesajları, sorunun kaynağını belirlemenize ve çözüm bulmanıza yardımcı olacaktır.

​
HTTP Hata Kodları

API’den dönen HTTP durum kodları, isteğinizin durumu hakkında bilgi verir. Başarılı istekler genellikle 200 OK durum kodu ile döner. Hata durumunda aşağıdaki kodlarla karşılaşabilirsiniz:

HTTP KoduHata MesajıAçıklamaÇözüm Önerisi
400Type parametresi gereklidirİstek gövdesinde Type parametresi bulunmamaktadırİstek gövdesine geçerli bir Type değeri ekleyin
400Geçersiz Type değeriDesteklenmeyen bir Type değeri gönderilmiştirGeçerli bir Type değeri kullanın (101-255 arası)
400StartDate parametresi gereklidirType kodu için gerekli olan StartDate parametresi eksikİstek gövdesine StartDate parametresi ekleyin
400EndDate parametresi gereklidirType kodu için gerekli olan EndDate parametresi eksikİstek gövdesine EndDate parametresi ekleyin
400BranchCode parametresi gereklidirType kodu için gerekli olan BranchCode parametresi eksikİstek gövdesine BranchCode parametresi ekleyin
401Geçersiz API anahtarıKimlik doğrulama başarısız olduAPI anahtarınızı kontrol edin ve doğru formatta gönderdiğinizden emin olun
403Yetkisiz erişimAPI anahtarı bu rapor türüne erişim izni vermiyorErişim izinlerinizi kontrol edin veya daha yüksek yetkili bir API anahtarı talep edin
404Type [kod] için rapor sorgu dosyası bulunamadıBelirtilen Type kodu için SQL sorgu dosyası bulunamadıGeçerli bir Type kodu kullandığınızdan emin olun
429İstek limiti aşıldıÇok fazla istek gönderildi, lütfen daha sonra tekrar deneyinİstek sayınızı azaltın veya istekleri zaman içinde dağıtın
500İç sunucu hatasıSunucu tarafında bir hata oluştuDaha sonra tekrar deneyin veya destek ekibiyle iletişime geçin
503Servis kullanılamıyorAPI bakım modunda veya geçici olarak kullanılamıyorDaha sonra tekrar deneyin

​
Hata Yanıt Formatı

API hata durumunda aşağıdaki formatta bir JSON yanıtı döndürür:

{
  "error": {
    "code": 400,
    "message": "Type parametresi gereklidir"
  },
  "timestamp": "2025-05-06T12:34:56.789Z"
}

Hata yanıtı her zaman bir error nesnesi içerir. Bu nesne içinde hata kodu (code) ve hata mesajı (message) bulunur. Ayrıca yanıtta hatanın oluştuğu zaman damgası (timestamp) da yer alır.

​
Hata Kodları Grupları

Hata kodları, aşağıdaki kategorilere ayrılabilir:

4xx - İstemci Hataları

Bu hatalar, istemci tarafından yapılan hatalı isteklerden kaynaklanır.

  • 400 - İstek formatı veya parametreleri hatalı
  • 401 - Kimlik doğrulama hatası
  • 403 - Yetkilendirme hatası
  • 404 - Kaynak bulunamadı
  • 429 - İstek limiti aşıldı

5xx - Sunucu Hataları

Bu hatalar, sunucu tarafında oluşan sorunlardan kaynaklanır.

  • 500 - İç sunucu hatası
  • 503 - Servis kullanılamıyor

​
Hata Yönetimi İpuçları

API isteklerinizde hataları etkili bir şekilde yönetmek için aşağıdaki önerileri dikkate alın:

  1. Hata Yakalama: Tüm API isteklerinizi try-catch blokları içinde yapın.
try {
  const response = await fetch('https://api.example.com/api/salesdata', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Type: 102,
      StartDate: '2025-05-01 00:00:00',
      EndDate: '2025-05-05 23:59:59',
      BranchCode: '0'
    })
  });
  
  const data = await response.json();
  
  if (!response.ok) {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }
  
  // Başarılı yanıtı işle
  console.log(data);
} catch (error) {
  console.error('API Hatası:', error.message);
  // Kullanıcıya hata mesajı göster
}
  1. Yeniden Deneme Stratejisi: 429 veya 5xx hataları için yeniden deneme mekanizması kullanın.
async function fetchWithRetry(url, options, maxRetries = 3, delay = 1000) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      if (response.ok) {
        return data;
      }
      
      // 429 veya 5xx hataları için yeniden dene
      if (response.status === 429 || response.status >= 500) {
        retries++;
        if (retries >= maxRetries) {
          throw new Error(`${data.error.code}: ${data.error.message}`);
        }
        
        // Üstel geri çekilme (exponential backoff)
        const waitTime = delay * Math.pow(2, retries - 1);
        console.log(`Yeniden deneniyor (${retries}/${maxRetries}) ${waitTime}ms sonra...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
      } else {
        // Diğer hata kodları için hemen hata fırlat
        throw new Error(`${data.error.code}: ${data.error.message}`);
      }
    } catch (error) {
      if (retries >= maxRetries) {
        throw error;
      }
    }
  }
}
  1. Hata Günlüğü: Tüm API hatalarını günlüğe kaydedin ve analiz edin.

Düzenli hata günlüğü analizi, API kullanımınızı optimize etmenize ve sorunları proaktif olarak çözmenize yardımcı olur.

​
Sık Karşılaşılan Sorunlar ve Çözümleri

401 - Geçersiz API anahtarı

API anahtarınızın doğru formatta olduğundan emin olun. API anahtarı, Authorization başlığında “Bearer” önekiyle birlikte gönderilmelidir.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

400 - Geçersiz Type değeri

Type değerinin desteklenen bir rapor tipi olduğundan emin olun. Geçerli Type değerleri 101-255 aralığındadır.

429 - İstek limiti aşıldı

API istek limitinizi aştınız. İsteklerinizi zaman içinde dağıtın veya daha yüksek limitli bir plan için bizimle iletişime geçin.

​
Destek Alın

API kullanımıyla ilgili sorunlarınız veya sorularınız için destek ekibimizle iletişime geçebilirsiniz.

API hatalarıyla ilgili destek talebi oluştururken, lütfen aşağıdaki bilgileri paylaşın:

  • Hata kodu ve mesajı
  • İstek detayları (endpoint, parametreler)
  • Hatanın oluştuğu tarih ve saat
  • Kullandığınız API anahtarının son 4 karakteri