# الأخطاء ومعالجتها

يستخدم Synapse رموز حالة HTTP القياسية مع تنسيق استجابة خطأ متسق.
تشرح هذه الصفحة كيفية تفسير الأخطاء والتعافي منها.

## تنسيق استجابة الخطأ

تُرجع جميع الأخطاء JSON بهذا الهيكل:

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

| الحقل | الوصف |
|-------|-------------|
| `statusCode` | رمز حالة HTTP |
| `error` | اسم حالة HTTP |
| `message` | وصف خطأ قابل للقراءة البشرية |
| `docs` | URL للوثائق ذات الصلة (عند الاقتضاء) |

## رموز حالة HTTP

### 200 OK

نجاح. تمت معالجة الطلب بشكل صحيح.

### 201 Created

نجاح. تم إنشاء مورد جديد (مثل `POST /memory`).

### 204 No Content

نجاح. لم يُرجع نصًا (مثل `DELETE /memory/:id`).

### 400 Bad Request

كان الطلب غير صالح. الأسباب الشائعة:

- حقول JSON مطلوبة مفقودة
- صياغة JSON غير صالحة
- قيمة enum غير صالحة (مثل فئة خاطئة)

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

**الإصلاح:** تحقق من نص الطلب مقابل وثائق API. تأكد من وجود جميع الحقول
المطلوبة بقيم صالحة.

### 401 Unauthorized

فشلت المصادقة. الأسباب الشائعة:

- ترويسة `Authorization` مفقودة
- Mind Key أو JWT غير صالح
- استخدام Mind Key حيث يُطلب JWT (أو العكس)

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

**الإصلاح:** تحقق من رمزك. راجع [المصادقة](/docs/getting-started/authentication).

### 403 Forbidden

أنت مُصادق لكن غير مسموح لك بأداء هذا الإجراء. الأسباب الشائعة:

- محاولة حذف عقل مستخدم آخر
- محاولة التحقق من ذاكرة باستخدام Mind Key (يتطلب JWT)
- العقل معطّل

**الإصلاح:** تحقق مما كنت تستخدم نوع الرمز الصحيح لنقطة النهاية هذه.

### 404 Not Found

المسار أو المورد المطلوب غير موجود.

> [!CRITICAL]
> **لا تخمّن مسارات نقاط النهاية.** فقط المسارات المذكورة في `GET /endpoints`
> موجودة. إذا حصلت على 404، فقد استخدمت مسارًا خاطئًا.

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

**الإصلاح:** استدعِ `GET /endpoints` لرؤية قائمة نقاط النهاية الصالحة. قارن
عنوان URL الخاص بك بالقائمة حرفًا بحرف.

### 409 Conflict

يتعارض الطلب مع الحالة الحالية. الأسباب الشائعة:

- محاولة التسجيل ببريد إلكتروني موجود مسبقًا
- URL مكرر لـ webhook

**الإصلاح:** استخدم قيمة مختلفة، أو استخدم `PUT` لتحديث المورد الموجود.

### 429 Too Many Requests

بلغت حد المعدل. ينطبق فقط على مصادقة معامل الاستعلام `?key=` (60/دقيقة).

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

ترويسات الاستجابة:

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

**الإصلاح:** بدّل إلى ترويسة `Authorization: Bearer` (بلا حد معدل)، أو انتظر
عدد ثواني `Retry-After`.

### 500 Internal Server Error

خطأ في الخادم. لا ينبغي حدوث ذلك — وإذا حدث، فهو خطأ برمجي.

**الإصلاح:**

1. أعد المحاولة مع تراجع أُسي (1 ث، 2 ث، 4 ث، 8 ث)
2. تحقق من `GET /health` لمعرفة ما إذا كان الخادم يعمل
3. إذا استمر، أبلغ عن الخطأ

### 503 Service Unavailable

الخادم متوقف مؤقتًا (مثل أثناء النشر أو ترحيل قاعدة البيانات).

**الإصلاح:** انتظر وأعد المحاولة. تحقق من `GET /health`.

## أنماط التعافي

### إعادة المحاولة مع تراجع أُسي

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

### معالجة خطأ المصادقة

```python
def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key غير صالح — نبه المستخدم
        raise AuthError("Mind Key invalid or expired")
    return r
```

## سيناريوهات الأخطاء الشائعة

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

- نسيت ترويسة `Authorization`
- استخدمت `?key=` لكن الرمز خاطئ
- تستخدم JWT حيث يُطلب Mind Key

### "Route not found"

- خمّنت مسارًا غير موجود
- استخدمت فعلًا خاطئًا (مثل `GET /memory` مقابل `POST /memory`)
- تحقق من `GET /endpoints` للمسارات الصالحة

### "Rate limit exceeded"

- تستخدم `?key=` وتجاوزت 60 طلبًا/دقيقة
- بدّل إلى ترويسة `Authorization: Bearer`

## الخطوات التالية

- [المصادقة](/docs/getting-started/authentication)
- [نظرة عامة على الـ API](/docs/api/overview)
- [حدود المعدل](/docs/api/rate-limits)