# Hatalar & Hata Yönetimi

Synapse, tutarlı bir hata yanıtı biçimiyle standart HTTP durum kodları kullanır. Bu sayfa hataları nasıl yorumlayacağınızı ve onlardan nasıl kurtulacağınızı açıklar.

## Hata Yanıtı Biçimi

Tüm hatalar bu yapıyla JSON döndürür:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

| Alan | Açıklama |
|-------|-------------|
| `statusCode` | HTTP durum kodu |
| `error` | HTTP durum adı |
| `message` | İnsan tarafından okunabilir hata açıklaması |
| `docs` | İlgili dokümantasyona URL (uygun olduğunda) |

## HTTP Durum Kodları

### 200 OK

Başarılı. İstek doğru şekilde işlendi.

### 201 Created

Başarılı. Yeni bir kaynak oluşturuldu (örn. `POST /memory`).

### 204 No Content

Başarılı. Gövde döndürülmedi (örn. `DELETE /memory/:id`).

### 400 Bad Request

İstek hatalı biçimlendirilmiş. Yaygın nedenler:

- Gerekli JSON alanları eksik
- Geçersiz JSON sözdizimi
- Geçersiz enum değeri (örn. yanlış kategori)

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"
}
```

**Çözüm:** İstek gövdesini API dokümanlarına göre kontrol edin. Tüm gerekli alanların mevcut olduğundan ve geçerli değerlere sahip olduğundan emin olun.

### 401 Unauthorized

Kimlik doğrulama başarısız. Yaygın nedenler:

- `Authorization` başlığı eksik
- Geçersiz Mind Key veya JWT
- Mind Key gerekendiye JWT kullanma (veya tersi)

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

**Çözüm:** Token'ınızı doğrulayın. Bkz. [Kimlik Doğrulama](/docs/getting-started/authentication).

### 403 Forbidden

Kimliği doğrulandı ancak bu eylemi gerçekleştirmeye izniniz yok. Yaygın nedenler:

- Başka bir kullanıcının mind'ini silmeye çalışmak
- Bir belleği Mind Key ile doğrulamaya çalışmak (JWT gerektirir)
- Mind devre dışı

**Çözüm:** Bu uç nokta için doğru token tipini kullanıp kullanmadığınızı kontrol edin.

### 404 Not Found

İstenen yol veya kaynak mevcut değil.

> [!CRITICAL]
> **Uç nokta yollarını TAHMİN ETMEYİN.** Yalnızca `GET /endpoints` içinde listelenen yollar mevcuttur. 404 alırsanız, yanlış bir yol kullandınız.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Route GET /memory/list not found",
  "docs": "https://synapse.schaefer.zone/docs/api/errors"
}
```

**Çözüm:** Geçerli uç noktaların listesini görmek için `GET /endpoints` çağırın. URL'nizi listeyle karakter karakter karşılaştırın.

### 409 Conflict

İstek mevcut durumla çakışıyor. Yaygın nedenler:

- Halihazırda var olan bir e-posta ile kaydolmaya çalışmak
- Yinelenen webhook URL'si

**Çözüm:** Farklı bir değer kullanın veya mevcut kaynağı güncellemek için `PUT` kullanın.

### 429 Too Many Requests

Hız sınırına çıktınız. Yalnızca `?key=` sorgu parametresi kimlik doğrulaması için geçerlidir (60/dak).

```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}
```

Yanıt başlıkları:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
```

**Çözüm:** `Authorization: Bearer` başlığına geçin (hız sınırı yoktur) veya `Retry-After` saniye kadar bekleyin.

### 500 Internal Server Error

Sunucu hatası. Bu olmamalı — olursa, bu bir hatadır.

**Çözüm:**

1. Üstel geri çekilme ile yeniden deneyin (1s, 2s, 4s, 8s)
2. Sunucunun çalışır durumda olup olmadığını görmek için `GET /health` kontrol edin
3. Sürekli olursa, hatayı bildirin

### 503 Service Unavailable

Sunucu geçici olarak devre dışı (örn. dağıtım sırasında, veritabanı taşıma).

**Çözüm:** Bekleyin ve yeniden deneyin. `GET /health` kontrol edin.

## Kurtarma Desenleri

### Üstel geri çekilme ile yeniden deneme

```python
import time
import requests

def call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})
            if r.status_code == 429:
                wait = int(r.headers.get("Retry-After", 60))
                time.sleep(wait)
                continue
            if r.status_code >= 500:
                time.sleep(2 ** attempt)
                continue
            return r
        except requests.RequestException:
            time.sleep(2 ** attempt)
    raise Exception(f"Failed after {max_retries} retries")
```

### Kimlik doğrulama hata yönetimi

```python
def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key invalid — alert user
        raise AuthError("Mind Key invalid or expired")
    return r
```

## Yaygın Hata Senaryoları

### "Mind Key fehlt oder ungültig"

- `Authorization` başlığını unuttunuz
- `?key=` kullandınız ama anahtar yanlış
- Mind Key gerekendiye JWT kullanıyorsunuz

### "Route not found"

- Var olmayan bir yolu tahmin ettiniz
- Bir fiili yanlış kullandınız (örn. `GET /memory` ve `POST /memory`)
- Geçerli yollar için `GET /endpoints` kontrol edin

### "Rate limit exceeded"

- `?key=` kullanıyorsunuz ve 60 istek/dakika sınırını aştınız
- `Authorization: Bearer` başlığına geçin

## Sonraki Adımlar

- [Kimlik Doğrulama](/docs/getting-started/authentication)
- [API Genel Bakış](/docs/api/overview)
- [Hız Sınırları](/docs/api/rate-limits)