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

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

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

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

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

رموز حالة HTTP

200 OK

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

201 Created

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

204 No Content

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

400 Bad Request

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

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

{
  "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 (أو العكس)

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

الإصلاح: تحقق من رمزك. راجع المصادقة.

403 Forbidden

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

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

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

404 Not Found

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

{
  "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/دقيقة).

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

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

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

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

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

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

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

• المصادقة
• نظرة عامة على الـ API
• حدود المعدل