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:

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

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)

{
  "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)

{
  "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.

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.

{
  "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).

{
  "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

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

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
• API Genel Bakış
• Hız Sınırları