Hata Kodları

Realtime Service API hata kodları ve açıklamaları

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 Kodu	Hata Mesajı	Açıklama	Çözüm Önerisi
400	Type parametresi gereklidir	İstek gövdesinde Type parametresi bulunmamaktadır	İstek gövdesine geçerli bir Type değeri ekleyin
400	Geçersiz Type değeri	Desteklenmeyen bir Type değeri gönderilmiştir	Geçerli bir Type değeri kullanın (101-255 arası)
400	StartDate parametresi gereklidir	Type kodu için gerekli olan StartDate parametresi eksik	İstek gövdesine StartDate parametresi ekleyin
400	EndDate parametresi gereklidir	Type kodu için gerekli olan EndDate parametresi eksik	İstek gövdesine EndDate parametresi ekleyin
400	BranchCode parametresi gereklidir	Type kodu için gerekli olan BranchCode parametresi eksik	İstek gövdesine BranchCode parametresi ekleyin
401	Geçersiz API anahtarı	Kimlik doğrulama başarısız oldu	API anahtarınızı kontrol edin ve doğru formatta gönderdiğinizden emin olun
403	Yetkisiz erişim	API anahtarı bu rapor türüne erişim izni vermiyor	Erişim izinlerinizi kontrol edin veya daha yüksek yetkili bir API anahtarı talep edin
404	Type [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ştu	Daha sonra tekrar deneyin veya destek ekibiyle iletişime geçin
503	Servis kullanılamıyor	API bakım modunda veya geçici olarak kullanılamıyor	Daha 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
}

2. 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;
      }
    }
  }
}

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

• E-posta: [e-mail]

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