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/minds",
  "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": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "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": "Mind 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

Güncel herkese açık varsayılanlar için oluşturulan plan limiti tablosuna bakın. Sözleşmeye özel geçersiz kılmalar farklı olabilir; bu nedenle kimliği doğrulanmış bir hatadaki data.limit ve data.current o istek için bağlayıcıdır. Starter planı API payload'larında "premium" olarak görünür.

Mind limiti örneği

Limite ulaşıldığında hata:

{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "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.

Kitle doğrulama hataları

10'dan az hazır Mind'ı olan bir Kitle için Kitle doğrulaması başlatmak, AUDIENCE_TOO_SMALL koduyla 422 döndürür. Planınızın bir Çalışmada izin verdiğinden büyük bir Kitle, yukarıda açıklanan standart plan limiti hatasıyla reddedilir.

Başarılı bir başlatmanın ardından doğrulama arka planda çalışır; bu yüzden hataların çoğu HTTP hatası değildir. Bunları doğrulama işinin (batch) failure alanından okuyun. Bir batch şu kodlardan biriyle bitebilir:

En İyi Uygulamalar

Hata İşleme

Hataları her zaman işleyin:

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

  const text = await response.text();
  let result = null;
  if (text) {
    try {
      result = JSON.parse(text);
    } catch {
      if (response.ok) throw new Error('Expected a JSON response');
    }
  }
  if (!response.ok) {
    throw Object.assign(new Error(result?.statusMessage || result?.message || `HTTP ${response.status}`), {
      status: response.status,
      data: result?.data,
      retryAfter: response.headers.get('Retry-After')
    });
  }
  return result;
}

Yeniden Deneme Mantığı

Akıllı yeniden denemeler uygulayın:

• Geçici 429 veya 5xx yanıtlarında okuma işlemlerini sınırlı üssel beklemeyle yeniden deneyin ve Retry-After değerine uyun. Yazma işlemlerini yalnızca uç nokta idempotency desteğini belgeliyorsa aynı anahtar ve istek gövdesiyle yeniden deneyin. Belirsiz bir zaman aşımından sonra tekrar göndermeden önce mevcut kaynağı veya işi kontrol edin.
• Ü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:

• Minds hizmet durumu
• 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
• Minds 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