---
title: "Hatalar ve Limitler"
description: "API hatalarını, durum kodlarını ve plan bazlı kaynak limitlerini anlayın."
---

# 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:

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

<table>
<thead>
  <tr>
    <th>
      Alan
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        statusCode
      </code>
    </td>
    
    <td>
      HTTP durum kodu
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        statusMessage
      </code>
    </td>
    
    <td>
      İnsan tarafından okunabilir hata açıklaması (handler tarafından hata başına ayarlanır — doğrulama hataları için bu, belirli sorundur, örn. <code>
        "Mind not found"
      </code>
      
       veya <code>
        "Invalid Mind ID format"
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        message
      </code>
    </td>
    
    <td>
      v1 hataları için <code>
        statusMessage
      </code>
      
       ile aynı içerik. Debug build'lerde <code>
        5xx
      </code>
      
       yanıtlarında stack/ekstra bağlam için ayrılmıştır.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      İstek yolu (Nuxt H3 tarafından eklenir)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      Hata yanıtları için <code>
        true
      </code>
      
       (Nuxt H3 tarafından eklenir)
    </td>
  </tr>
</tbody>
</table>

> 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ı

<table>
<thead>
  <tr>
    <th>
      Kod
    </th>
    
    <th>
      Durum
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      200
    </td>
    
    <td>
      OK
    </td>
    
    <td>
      İstek başarılı
    </td>
  </tr>
  
  <tr>
    <td>
      201
    </td>
    
    <td>
      Created
    </td>
    
    <td>
      Kaynak başarıyla oluşturuldu (örn. <code>
        POST /minds
      </code>
      
      , <code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      202
    </td>
    
    <td>
      Accepted
    </td>
    
    <td>
      İstek asenkron işleme için kabul edildi (örn. <code>
        keywords
      </code>
      
       ile <code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      204
    </td>
    
    <td>
      No Content
    </td>
    
    <td>
      İstek başarılı, yanıt body'si yok (örn. <code>
        DELETE /minds/{id}/knowledge/{itemId}
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 4xx İstemci Hataları

<table>
<thead>
  <tr>
    <th>
      Kod
    </th>
    
    <th>
      Durum
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      Bad Request
    </td>
    
    <td>
      Geçersiz istek parametreleri
    </td>
  </tr>
  
  <tr>
    <td>
      401
    </td>
    
    <td>
      Unauthorized
    </td>
    
    <td>
      Eksik veya geçersiz API key
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      Forbidden
    </td>
    
    <td>
      Erişim reddedildi veya plan limitine ulaşıldı
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      Not Found
    </td>
    
    <td>
      Kaynak mevcut değil
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      Unsupported Media Type
    </td>
    
    <td>
      Yanlış Content-Type header'ı
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      Too Many Requests
    </td>
    
    <td>
      Rate limit aşıldı
    </td>
  </tr>
</tbody>
</table>

### 5xx Sunucu Hataları

<table>
<thead>
  <tr>
    <th>
      Kod
    </th>
    
    <th>
      Durum
    </th>
    
    <th>
      Açıklama
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      500
    </td>
    
    <td>
      Internal Server Error
    </td>
    
    <td>
      Sunucu tarafı hata
    </td>
  </tr>
  
  <tr>
    <td>
      503
    </td>
    
    <td>
      Service Unavailable
    </td>
    
    <td>
      Servis geçici olarak kullanılamıyor
    </td>
  </tr>
</tbody>
</table>

## Yaygın Hatalar

### 400 Bad Request

**Eksik Zorunlu Alan:**

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

**Geçersiz Giriş:**

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

### 401 Unauthorized

**Eksik API Key:**

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

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

```bash
-H "Authorization: Bearer minds_your_api_key"
```

### 403 Forbidden

**Plan Limitine Ulaşıldı:**

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

**Erişim Reddedildi:**

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

### 404 Not Found

**Kaynak Mevcut Değil:**

```json
{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}
```

### 415 Unsupported Media Type

**Yanlış Content-Type:**

```json
{
  "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ı:**

```json
{
  "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](/docs/api/overview) 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. Individual planı API payload'larında `"premium"` olarak görünür.

### Mind limiti örneği

**Limite ulaşıldığında hata:**

```json
{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual 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.

## En İyi Uygulamalar

### Hata İşleme

**Hataları her zaman işleyin:**

```javascript
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](/settings?tab=subscription)

## Yardım Alma

### Durumu Kontrol Edin

Servis durumumuzu izleyin:

- [Minds hizmet durumu](https://uptime.getminds.ai)
- Güncellemeler için [@mindsai_co](https://x.com/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: [support@getminds.ai](mailto:support@getminds.ai)

### Dokümantasyonu İnceleyin

- [API Overview](/docs/api/overview)
- [Authentication](/docs/api/authentication)
- [Minds API](/docs/api/minds)
- [Knowledge API](/docs/api/knowledge)
- [Chat API](/docs/api/chat)

## Durum Kodları Referansı

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

```text
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
```