{"title":"Hatalar & Hata Yönetimi","slug":"errors","category":"api","summary":"HTTP durum kodları, hata yanıtı biçimi ve yaygın hatalardan nasıl kurtulunacağı.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":473,"read_minutes":2,"llm_context":"Error format: { statusCode, error, message, docs? }\nCommon errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)\n401 → check Mind Key/JWT, see /docs/getting-started/authentication\n404 → wrong path, GET /endpoints for valid list, do NOT guess paths\n429 → rate limited (?key= is 60/min), use Bearer header instead\n500 → server error, retry with backoff, check /health\ndocs field in error response links to relevant documentation.\n","lang":"tr","translated":true,"requested_lang":"tr","content_markdown":"\n# Hatalar & Hata Yönetimi\n\nSynapse, 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.\n\n## Hata Yanıtı Biçimi\n\nTüm hatalar bu yapıyla JSON döndürür:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n| Alan | Açıklama |\n|-------|-------------|\n| `statusCode` | HTTP durum kodu |\n| `error` | HTTP durum adı |\n| `message` | İnsan tarafından okunabilir hata açıklaması |\n| `docs` | İlgili dokümantasyona URL (uygun olduğunda) |\n\n## HTTP Durum Kodları\n\n### 200 OK\n\nBaşarılı. İstek doğru şekilde işlendi.\n\n### 201 Created\n\nBaşarılı. Yeni bir kaynak oluşturuldu (örn. `POST /memory`).\n\n### 204 No Content\n\nBaşarılı. Gövde döndürülmedi (örn. `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nİstek hatalı biçimlendirilmiş. Yaygın nedenler:\n\n- Gerekli JSON alanları eksik\n- Geçersiz JSON sözdizimi\n- Geçersiz enum değeri (örn. yanlış kategori)\n\n```json\n{\n \"statusCode\": 400,\n \"error\": \"Bad Request\",\n \"message\": \"category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials\"\n}\n```\n\n**Çö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.\n\n### 401 Unauthorized\n\nKimlik doğrulama başarısız. Yaygın nedenler:\n\n- `Authorization` başlığı eksik\n- Geçersiz Mind Key veya JWT\n- Mind Key gerekendiye JWT kullanma (veya tersi)\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n**Çözüm:** Token'ınızı doğrulayın. Bkz. [Kimlik Doğrulama](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nKimliği doğrulandı ancak bu eylemi gerçekleştirmeye izniniz yok. Yaygın nedenler:\n\n- Başka bir kullanıcının mind'ini silmeye çalışmak\n- Bir belleği Mind Key ile doğrulamaya çalışmak (JWT gerektirir)\n- Mind devre dışı\n\n**Çözüm:** Bu uç nokta için doğru token tipini kullanıp kullanmadığınızı kontrol edin.\n\n### 404 Not Found\n\nİstenen yol veya kaynak mevcut değil.\n\n> [!CRITICAL]\n> **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.\n\n```json\n{\n \"statusCode\": 404,\n \"error\": \"Not Found\",\n \"message\": \"Route GET /memory/list not found\",\n \"docs\": \"https://synapse.schaefer.zone/docs/api/errors\"\n}\n```\n\n**Çö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.\n\n### 409 Conflict\n\nİstek mevcut durumla çakışıyor. Yaygın nedenler:\n\n- Halihazırda var olan bir e-posta ile kaydolmaya çalışmak\n- Yinelenen webhook URL'si\n\n**Çözüm:** Farklı bir değer kullanın veya mevcut kaynağı güncellemek için `PUT` kullanın.\n\n### 429 Too Many Requests\n\nHız sınırına çıktınız. Yalnızca `?key=` sorgu parametresi kimlik doğrulaması için geçerlidir (60/dak).\n\n```json\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\nYanıt başlıkları:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Çözüm:** `Authorization: Bearer` başlığına geçin (hız sınırı yoktur) veya `Retry-After` saniye kadar bekleyin.\n\n### 500 Internal Server Error\n\nSunucu hatası. Bu olmamalı — olursa, bu bir hatadır.\n\n**Çözüm:**\n\n1. Üstel geri çekilme ile yeniden deneyin (1s, 2s, 4s, 8s)\n2. Sunucunun çalışır durumda olup olmadığını görmek için `GET /health` kontrol edin\n3. Sürekli olursa, hatayı bildirin\n\n### 503 Service Unavailable\n\nSunucu geçici olarak devre dışı (örn. dağıtım sırasında, veritabanı taşıma).\n\n**Çözüm:** Bekleyin ve yeniden deneyin. `GET /health` kontrol edin.\n\n## Kurtarma Desenleri\n\n### Üstel geri çekilme ile yeniden deneme\n\n```python\nimport time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n for attempt in range(max_retries):\n try:\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {KEY}\"})\n if r.status_code == 429:\n wait = int(r.headers.get(\"Retry-After\", 60))\n time.sleep(wait)\n continue\n if r.status_code >= 500:\n time.sleep(2 ** attempt)\n continue\n return r\n except requests.RequestException:\n time.sleep(2 ** attempt)\n raise Exception(f\"Failed after {max_retries} retries\")\n```\n\n### Kimlik doğrulama hata yönetimi\n\n```python\ndef safe_call(url, key):\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {key}\"})\n if r.status_code == 401:\n # Mind Key invalid — alert user\n raise AuthError(\"Mind Key invalid or expired\")\n return r\n```\n\n## Yaygın Hata Senaryoları\n\n### \"Mind Key fehlt oder ungültig\"\n\n- `Authorization` başlığını unuttunuz\n- `?key=` kullandınız ama anahtar yanlış\n- Mind Key gerekendiye JWT kullanıyorsunuz\n\n### \"Route not found\"\n\n- Var olmayan bir yolu tahmin ettiniz\n- Bir fiili yanlış kullandınız (örn. `GET /memory` ve `POST /memory`)\n- Geçerli yollar için `GET /endpoints` kontrol edin\n\n### \"Rate limit exceeded\"\n\n- `?key=` kullanıyorsunuz ve 60 istek/dakika sınırını aştınız\n- `Authorization: Bearer` başlığına geçin\n\n## Sonraki Adımlar\n\n- [Kimlik Doğrulama](/docs/getting-started/authentication)\n- [API Genel Bakış](/docs/api/overview)\n- [Hız Sınırları](/docs/api/rate-limits)\n","content_html":"

Hatalar & Hata Yönetimi

\n

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.

\n

Hata Yanıtı Biçimi

\n

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

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AlanAçıklama
statusCodeHTTP durum kodu
errorHTTP durum adı
messageİnsan tarafından okunabilir hata açıklaması
docsİlgili dokümantasyona URL (uygun olduğunda)
\n

HTTP Durum Kodları

\n

200 OK

\n

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

\n

201 Created

\n

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

\n

204 No Content

\n

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

\n

400 Bad Request

\n

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

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

Çö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.

\n

401 Unauthorized

\n

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

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

Çözüm: Token'ınızı doğrulayın. Bkz. Kimlik Doğrulama.

\n

403 Forbidden

\n

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

\n\n

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

\n

404 Not Found

\n

İstenen yol veya kaynak mevcut değil.

\n
**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.
{\n  "statusCode": 404,\n  "error": "Not Found",\n  "message": "Route GET /memory/list not found",\n  "docs": "https://synapse.schaefer.zone/docs/api/errors"\n}

Çö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.

\n

409 Conflict

\n

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

\n\n

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

\n

429 Too Many Requests

\n

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

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

Yanıt başlıkları:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42

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

\n

500 Internal Server Error

\n

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

\n

Çözüm:

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

503 Service Unavailable

\n

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

\n

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

\n

Kurtarma Desenleri

\n

Üstel geri çekilme ile yeniden deneme

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

Kimlik doğrulama hata yönetimi

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

Yaygın Hata Senaryoları

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

Sonraki Adımlar

\n\n","urls":{"html":"/docs/api/errors","text":"/docs/api/errors?format=text","json":"/docs/api/errors?format=json","llm":"/docs/api/errors?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}