Hata Kodları

SignaPort API'de oluşabilecek tüm hata kodları ve çözüm yöntemleri.

Hata Formatı

Tüm hata yanıtları standart JSON formatında döner:

{
  "success": false,
  "message": "Hata açıklaması"
}

veya

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Hata açıklaması"
  }
}

HTTP Status Kodları

Kod	Anlam	Kullanım
200	OK	İstek başarılı
400	Bad Request	Geçersiz parametre
401	Unauthorized	Kimlik doğrulama hatası
404	Not Found	Kaynak bulunamadı
429	Too Many Requests	Rate limit aşıldı
500	Internal Server Error	Sunucu hatası

Authentication Hataları

INVALID_REQUEST

HTTP Status: 400

Sebep: Eksik veya geçersiz parametreler

Response:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Geçersiz istek parametreleri"
  }
}

Çözüm: Request body'deki parametreleri kontrol edin (licenseKey, password, imzaTipi).

---

INVALID_CREDENTIALS

HTTP Status: 401

Sebep: Yanlış licenseKey veya password

Response:

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Geçersiz lisans bilgileri"
  }
}

Çözüm: Lisans anahtarı ve şifrenizi kontrol edin.

---

LICENSE_EXPIRED

HTTP Status: 401

Sebep: Lisans süresi dolmuş

Response:

{
  "success": false,
  "error": {
    "code": "LICENSE_EXPIRED",
    "message": "Lisans süresi dolmuş"
  }
}

Çözüm: Lisansınızı yenileyiniz.

---

LICENSE_INACTIVE

HTTP Status: 401

Sebep: Lisans pasif durumda

Response:

{
  "success": false,
  "error": {
    "code": "LICENSE_INACTIVE",
    "message": "Lisans aktif değil"
  }
}

Çözüm: Lisans yöneticinizle iletişime geçiniz.

---

Token Hataları

Token boş olamaz

HTTP Status: 400

Response:

{
  "success": false,
  "message": "Token boş olamaz"
}

Çözüm: Request body'de token parametresini gönderin.

---

Token süresi dolmuş

HTTP Status: 401

Sebep: Token'ın 5 dakikalık süresi dolmuş

Response:

{
  "success": false,
  "message": "Token süresi dolmuş"
}

Çözüm: /api/v1/auth/get-token endpoint'inden yeni token alın.

---

Geçersiz token

HTTP Status: 401

Sebep: Token formatı yanlış, signature geçersiz veya decode edilemiyor

Response:

{
  "success": false,
  "message": "Geçersiz token"
}

Çözüm: Yeni token alın.

---

TOKEN_ALREADY_USED

HTTP Status: 400

Sebep: Token daha önce kullanılmış (tek kullanımlık)

Response:

{
  "success": false,
  "message": "Bu token zaten kullanılmış. Yeni token alınız."
}

Çözüm: Her imzalama için yeni token alın.

---

Quota Hataları

INSUFFICIENT_QUOTA

HTTP Status: 400

Sebep: İmza kontörü yetersiz

Response:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_QUOTA",
    "message": "İmza kotası yetersiz"
  }
}

Çözüm: Yeni kontör paketi satın alın.

---

İmza kotası doldu

HTTP Status: 400

Sebep: Kalan kontör 0

Response:

{
  "success": false,
  "message": "İmza kotası doldu",
  "remainingQuota": 0
}

Çözüm: Yeni kontör paketi satın alın.

---

Domain Hataları

Bu domain için yetki yok

HTTP Status: 401

Sebep: Origin header'daki domain izinli değil

Response:

{
  "success": false,
  "message": "Bu domain için yetki yok"
}

Çözüm: Domain'inizi lisansa ekletiniz veya izinli domain'den istek yapınız.

---

Kaynak Hataları

Lisans bulunamadı

HTTP Status: 404

Sebep: Girilen licenseKey sistemde yok

Response:

{
  "success": false,
  "message": "Lisans bulunamadı"
}

Çözüm: License key'inizi kontrol edin.

---

Rate Limiting Hataları

Çok fazla istek

HTTP Status: 429

Sebep: Dakikalık istek limiti aşıldı

Response:

{
  "success": false,
  "message": "Çok fazla istek. Lütfen bekleyiniz.",
  "retryAfter": 45
}

Çözüm: retryAfter saniye bekleyip tekrar deneyin.

---

Sunucu Hataları

Internal Server Error

HTTP Status: 500

Sebep: Sunucu tarafında beklenmeyen hata

Response:

{
  "success": false,
  "message": "Sunucu hatası oluştu"
}

Çözüm: Tekrar deneyin. Sorun devam ederse destek ile iletişime geçin.

---

Hata Yönetimi Stratejileri

Retry Mekanizması

async function apiCallWithRetry(fn, maxRetries = 3) {
  const nonRetryableErrors = [
    'Token süresi dolmuş',
    'zaten kullanılmış',
    'kotası doldu',
    'Geçersiz token',
    'Geçersiz lisans'
  ];
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      // Retry yapılmaması gereken hatalar
      if (nonRetryableErrors.some(e => error.message.includes(e))) {
        throw error;
      }
      
      // Son deneme
      if (i === maxRetries - 1) {
        throw error;
      }
      
      // Exponential backoff
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }
}

Kullanıcıya Mesaj Gösterme

function getUserFriendlyMessage(error) {
  const messages = {
    'Token süresi dolmuş': 'İşlem süresi doldu. Lütfen tekrar deneyin.',
    'zaten kullanılmış': 'Bu işlem zaten yapılmış.',
    'kotası doldu': 'İmza hakkınız bitmiştir. Yeni paket satın alınız.',
    'Geçersiz token': 'Kimlik doğrulama hatası. Lütfen tekrar giriş yapın.',
    'domain için yetki yok': 'Bu işlem için yetkiniz yoktur.',
    'Çok fazla istek': 'Çok hızlı işlem yapıyorsunuz. Lütfen bekleyin.',
    'Geçersiz lisans': 'Lisans bilgileriniz hatalı. Lütfen kontrol edin.'
  };
  
  for (const [key, msg] of Object.entries(messages)) {
    if (error.message.includes(key)) {
      return msg;
    }
  }
  
  return 'Bir hata oluştu. Lütfen tekrar deneyin.';
}

Hata Loglama

function logError(context, error) {
  const log = {
    timestamp: new Date().toISOString(),
    context: context,
    error: {
      message: error.message,
      code: error.code,
      stack: error.stack
    },
    userAgent: navigator.userAgent,
    url: window.location.href
  };
  
  // Backend'e gönder
  fetch('/api/logs/error', {
    method: 'POST',
    body: JSON.stringify(log)
  });
  
  console.error('SignaPort Error:', log);
}

Özet Tablo

Hata	HTTP	Endpoint	Retry	Çözüm
INVALID_REQUEST	400	get-token	Hayır	Parametreleri düzelt
INVALID_CREDENTIALS	401	get-token	Hayır	Kimlik bilgileri kontrol
INSUFFICIENT_QUOTA	400	get-token	Hayır	Kontör satın al
LICENSE_EXPIRED	401	get-token	Hayır	Lisans yenile
LICENSE_INACTIVE	401	get-token	Hayır	Destek ile iletişim
TOKEN_ALREADY_USED	400	validate	Hayır	Yeni token al
Token süresi dolmuş	401	validate	Hayır	Yeni token al
Geçersiz token	401	validate	Hayır	Yeni token al
Domain yetkisi yok	401	validate	Hayır	Domain ekle
Kontör doldu	400	validate	Hayır	Kontör satın al
Lisans bulunamadı	404	check-quota	Hayır	License key kontrol
Rate limit	429	Tümü	Evet	Bekle ve tekrar dene
Server error	500	Tümü	Evet	Tekrar dene

Destek

Hata çözümünde yardım için:

E-posta: support@akareisg.com

Telefon: +90 XXX XXX XX XX

Çalışma Saatleri: Hafta içi 09:00 - 18:00

Destek talebinde belirtiniz:

• Endpoint URL
• Request body (şifreler hariç)
• Response (tam hata mesajı)
• Tarih ve saat
• License key