# الأخطاء ومعالجتها
SUMMARY: رموز حالة HTTP وتنسيق استجابة الخطأ وكيفية التعافي من الأخطاء الشائعة.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

الأخطاء ومعالجتها
يستخدم Synapse رموز حالة HTTP القياسية مع تنسيق استجابة خطأ متسق.
تشرح هذه الصفحة كيفية تفسير الأخطاء والتعافي منها.
تنسيق استجابة الخطأ
تُرجع جميع الأخطاء JSON بهذا الهيكل:
[CODE BLOCK]
| الحقل | الوصف |
|-------|-------------|
|  | رمز حالة HTTP |
|  | اسم حالة HTTP |
|  | وصف خطأ قابل للقراءة البشرية |
|  | URL للوثائق ذات الصلة (عند الاقتضاء) |
رموز حالة HTTP
200 OK
نجاح. تمت معالجة الطلب بشكل صحيح.
201 Created
نجاح. تم إنشاء مورد جديد (مثل ).
204 No Content
نجاح. لم يُرجع نصًا (مثل ).
400 Bad Request
كان الطلب غير صالح. الأسباب الشائعة:
- حقول JSON مطلوبة مفقودة
- صياغة JSON غير صالحة
- قيمة enum غير صالحة (مثل فئة خاطئة)
[CODE BLOCK]
الإصلاح: تحقق من نص الطلب مقابل وثائق API. تأكد من وجود جميع الحقول
المطلوبة بقيم صالحة.
401 Unauthorized
فشلت المصادقة. الأسباب الشائعة:
- ترويسة  مفقودة
- Mind Key أو JWT غير صالح
- استخدام Mind Key حيث يُطلب JWT (أو العكس)
[CODE BLOCK]
الإصلاح: تحقق من رمزك. راجع المصادقة.
403 Forbidden
أنت مُصادق لكن غير مسموح لك بأداء هذا الإجراء. الأسباب الشائعة:
- محاولة حذف عقل مستخدم آخر
- محاولة التحقق من ذاكرة باستخدام Mind Key (يتطلب JWT)
- العقل معطّل
الإصلاح: تحقق مما كنت تستخدم نوع الرمز الصحيح لنقطة النهاية هذه.
404 Not Found
المسار أو المورد المطلوب غير موجود.
> [!CRITICAL]
> لا تخمّن مسارات نقاط النهاية. فقط المسارات المذكورة في 
> موجودة. إذا حصلت على 404، فقد استخدمت مسارًا خاطئًا.
[CODE BLOCK]
الإصلاح: استدعِ  لرؤية قائمة نقاط النهاية الصالحة. قارن
عنوان URL الخاص بك بالقائمة حرفًا بحرف.
409 Conflict
يتعارض الطلب مع الحالة الحالية. الأسباب الشائعة:
- محاولة التسجيل ببريد إلكتروني موجود مسبقًا
- URL مكرر لـ webhook
الإصلاح: استخدم قيمة مختلفة، أو استخدم  لتحديث المورد الموجود.
429 Too Many Requests
بلغت حد المعدل. ينطبق فقط على مصادقة معامل الاستعلام  (60/دقيقة).
[CODE BLOCK]
ترويسات الاستجابة:
[CODE BLOCK]
الإصلاح: بدّل إلى ترويسة  (بلا حد معدل)، أو انتظر
عدد ثواني .
500 Internal Server Error
خطأ في الخادم. لا ينبغي حدوث ذلك — وإذا حدث، فهو خطأ برمجي.
الإصلاح:
1. أعد المحاولة مع تراجع أُسي (1 ث، 2 ث، 4 ث، 8 ث)
2. تحقق من  لمعرفة ما إذا كان الخادم يعمل
3. إذا استمر، أبلغ عن الخطأ
503 Service Unavailable
الخادم متوقف مؤقتًا (مثل أثناء النشر أو ترحيل قاعدة البيانات).
الإصلاح: انتظر وأعد المحاولة. تحقق من .
أنماط التعافي
إعادة المحاولة مع تراجع أُسي
[CODE BLOCK]
معالجة خطأ المصادقة
[CODE BLOCK]
سيناريوهات الأخطاء الشائعة
"Mind Key fehlt oder ungültig"
- نسيت ترويسة 
- استخدمت  لكن الرمز خاطئ
- تستخدم JWT حيث يُطلب Mind Key
"Route not found"
- خمّنت مسارًا غير موجود
- استخدمت فعلًا خاطئًا (مثل  مقابل )
- تحقق من  للمسارات الصالحة
"Rate limit exceeded"
- تستخدم  وتجاوزت 60 طلبًا/دقيقة
- بدّل إلى ترويسة 
الخطوات التالية
- المصادقة
- نظرة عامة على الـ API
- حدود المعدل