Hatalar ve Limitler

API hatalarını, rate limit'leri ve plan kısıtlamalarını anlama.

Hata Yanıt Formatı

Tüm hatalar tutarlı bir formatı takip eder:

{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/sparks",
  "error": true
}

Programatik işleme için her zaman statusCode'a ve insan tarafından okunabilir neden için statusMessage'a (veya message) güvenin. url ve error alanları, temel framework'ten gelen kullanışlı metadata'dır.

HTTP Durum Kodları

2xx Başarı

4xx İstemci Hataları

5xx Sunucu Hataları

Yaygın Hatalar

400 Bad Request

Eksik Zorunlu Alan:

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

Geçersiz Giriş:

{
  "statusCode": 400,
  "statusMessage": "File too large: document.pdf (55.2MB). Maximum size is 50MB."
}

401 Unauthorized

Eksik API Key:

{
  "statusCode": 401,
  "statusMessage": "Unauthorized"
}

Çözüm: Authorization header'ını ekleyin:

-H "Authorization: Bearer minds_your_api_key"

403 Forbidden

Plan Limitine Ulaşıldı:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Erişim Reddedildi:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

Kaynak Mevcut Değil:

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

415 Unsupported Media Type

Yanlış Content-Type:

{
  "statusCode": 415,
  "statusMessage": "Unsupported Content-Type. Use application/json for links or multipart/form-data for files"
}

Çözüm: Doğru Content-Type header'ını kullanın:

• JSON istekleri için application/json
• Dosya yüklemeleri için multipart/form-data

429 Too Many Requests

Rate Limit Aşıldı:

{
  "statusCode": 429,
  "statusMessage": "Too many requests. Please try again later."
}

Rate Limit'ler

v1 API kimliği doğrulanmış hesap başına sabit pencere sınırı uygular. Varsayılan dağıtım sınırı dakikada 300 istektir ancak yapılandırılabilir. Her zaman RateLimit-Limit ve RateLimit-Remaining başlıklarını okuyun; 429 sonrasında Retry-After içinde belirtilen saniye kadar bekleyin.

Plan Limitleri

Farklı planların farklı kaynak limitleri vardır.

Mind Limitleri

Limite ulaşıldığında hata:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Bilgi Yükleme Limitleri

• Dosya Boyutu: Dosya başına maksimum 50MB (tüm planlar)
• Depolama: Şu anda açık depolama limiti uygulanmıyor

API Key Limitleri

• Maksimum Key: Şu anda herhangi bir üst sınır uygulanmıyor.

En İyi Uygulamalar

Hata İşleme

Hataları her zaman işleyin:

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.statusCode}: ${error.message}`);
    // Handle specific errors
    if (error.statusCode === 429) {
      // Implement retry logic
    }
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error('Network error:', error);
}

Yeniden Deneme Mantığı

Akıllı yeniden denemeler uygulayın:

• 429 (rate limit) ve 5xx hatalarında yeniden deneyin
• Üssel geri çekilme (exponential backoff) kullanın
• Maksimum yeniden deneme sayısı belirleyin
• 4xx hatalarında yeniden denemeyin (429 hariç)

İzleme

Kullanımınızı takip edin:

• Rate limit header'larını loglayın
• Hata oranlarını izleyin
• Tekrarlayan hatalar için alertler kurun
• Yanıt sürelerini takip edin

Gerektiğinde Yükseltin

Şu durumlarda planınızı yükseltin:

• Sık sık rate limit'e takılıyorsanız
• Daha fazla mind'a ihtiyacınız varsa
• Daha büyük dosya yüklemeleri gerekiyorsa
• Öncelikli destek istiyorsanız

Planları Görüntüle

Yardım Alma

Durumu Kontrol Edin

Servis durumumuzu izleyin:

• Status sayfası (yakında)
• Güncellemeler için @mindsai_co hesabını takip edin

Destek İletişim

Aşağıdakileri yaşıyorsanız:

• Kalıcı 500 hataları
• Yanlış rate limit uygulanması
• Beklenmedik davranış

Bize ulaşın:

• Geri bildirim formu
• E-posta: [email protected]

Dokümantasyonu İnceleyin

• API Overview
• Authentication
• Sparks API
• Knowledge API
• Chat API

Durum Kodları Referansı

Tüm HTTP durum kodları için hızlı referans:

2xx Success
├─ 200 OK
└─ 201 Created

4xx Client Error
├─ 400 Bad Request
├─ 401 Unauthorized
├─ 403 Forbidden
├─ 404 Not Found
├─ 415 Unsupported Media Type
└─ 429 Too Many Requests

5xx Server Error
├─ 500 Internal Server Error
└─ 503 Service Unavailable